JBoss Enterprise Application Platform 6.4

Administration and Configuration Guide

For Use with Red Hat JBoss Enterprise Application Platform 6

Red Hat Customer Content Services

Legal Notice

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

Abstract

This book is a guide to the administration and configuration of Red Hat JBoss Enterprise Application Platform 6 and its patch releases.
1. Introduction
1.1. About Red Hat JBoss Enterprise Application Platform 6
1.2. Features of JBoss EAP 6
1.3. About JBoss EAP 6 Operating Modes
1.4. About Standalone Servers
1.5. About Managed Domains
1.6. About the Domain Controller
1.7. About Domain Controller Discovery and Failover
1.8. About Host Controller
1.9. About Server Groups
1.10. About JBoss EAP 6 Profiles
1.11. Manage Servers of Different Versions
2. Application Server Management
2.1. JBoss EAP Documentation Conventions
2.2. Start and Stop JBoss EAP 6
2.2.1. Start JBoss EAP 6
2.2.2. Start JBoss EAP 6 as a Standalone Server
2.2.3. Running Multiple JBoss EAP Standalone Servers on a Single Machine
2.2.4. Start JBoss EAP 6 as a Managed Domain
2.2.5. Configure the Name of a Host in a Managed Domain
2.2.6. Create Managed Domain on Two Machines
2.2.7. Create Managed Domain on a Single Machine
2.2.8. Start JBoss EAP 6 with an Alternative Configuration
2.2.9. Stop JBoss EAP 6
2.2.10. Reference of Switches and Arguments to pass at Server Runtime
2.3. Start and Stop Servers
2.3.1. Start and Stop Servers Using the Management CLI
2.3.2. Start a Server Using the Management Console
2.3.3. Stop a Server Using the Management Console
2.4. Configuration Files
2.4.1. About JBoss EAP 6 Configuration Files
2.4.2. Back up JBoss EAP Configuration Data
2.4.3. Descriptor-based Property Replacement
2.4.4. Enabling or Disabling Descriptor Based Property Replacement
2.4.5. Nested Expressions
2.4.6. Configuration File History
2.4.7. Start the Server with a Previous Configuration
2.4.8. Save a Configuration Snapshot Using the Management CLI
2.4.9. Load a Configuration Snapshot Using the Management CLI
2.4.10. Delete a Configuration Snapshot Using Management CLI
2.4.11. List All Configuration Snapshots Using Management CLI
2.5. Filesystem Paths
2.5.1. Directory Grouping
2.5.2. Use Case: Overriding Directories
3. Management Interfaces
3.1. Manage the Application Server
3.2. Management Application Programming Interfaces (APIs)
3.3. The Management Console
3.3.1. Management Console
3.3.2. Log in to the Management Console
3.3.3. Change the Language of the Management Console
3.3.4. Analytics in JBoss EAP Console
3.3.5. Enable Google Analytics in JBoss EAP Console
3.3.6. Disable Google Analytics in JBoss EAP Console
3.3.7. Configure a Server Using the Management Console
3.3.8. Add a Deployment in the Management Console
3.3.9. Create a New Server in the Management Console
3.3.10. Change the Default Log Levels Using the Management Console
3.3.11. Create a New Server Group in the Management Console
3.3.12. Viewing Logs in the Management Console
3.3.13. Customer Portal Integration in the Management Console
3.4. The Management CLI
3.4.1. About the Management Command Line Interface (CLI)
3.4.2. Launch the Management CLI
3.4.3. Quit the Management CLI
3.4.4. Connect to a Managed Server Instance Using the Management CLI
3.4.5. Obtain Help with the Management CLI
3.4.6. Use the Management CLI in Batch Mode
3.4.7. CLI Batch Mode Commands
3.4.8. Use Operations and Commands in the Management CLI
3.4.9. Use if-else Control Flow with the Management CLI
3.4.10. Management CLI Configuration Options
3.4.11. Reference of Management CLI Commands
3.4.12. Reference of Management CLI Operations
3.4.13. Property Substitution in the Management CLI
3.5. Management CLI Operations
3.5.1. Display the Attributes of a Resource with the Management CLI
3.5.2. Display the Active User in the Management CLI
3.5.3. Display System and Server Information in the Management CLI
3.5.4. Display an Operation Description using the Management CLI
3.5.5. Display the Operation Names using the Management CLI
3.5.6. Display Available Resources using the Management CLI
3.5.7. Display Available Resource Descriptions using the Management CLI
3.5.8. Reload the Application Server using the Management CLI
3.5.9. Shut the Application Server down using the Management CLI
3.5.10. Configure an Attribute with the Management CLI
3.5.11. Configure System Properties Using the Management CLI
3.5.12. Create a New Server with the Management CLI
3.6. The Management CLI Command History
3.6.1. About the Management CLI Command History
3.6.2. View Management CLI Command History
3.6.3. Clear the Management CLI Command History
3.6.4. Disable the Management CLI Command History
3.6.5. Enable the Management CLI Command History
3.7. Management Interface Audit Logging
3.7.1. About Management Interface Audit Logging
3.7.2. Enable Management Interface Audit Logging to a File
3.7.3. Enable Management Interface Audit Logging to a Syslog Server
3.7.4. Disable Management Interface Audit Logging
3.7.5. Read a Management Interface Audit Log
4. User Management
4.1. About JBoss EAP User Management
4.2. User Creation
4.2.1. Add the User for the Management Interfaces
4.2.2. Pass Arguments to the User Management add-user Script
4.2.3. Add-user Command Arguments
4.2.4. Specify Alternate Properties Files for User Management Information
4.3. Add-user Script Command Line Examples
4.3.1. Create a User Belonging to a Single Group Using the Default Properties Files
4.3.2. Create a User Belonging to Multiple Groups Using the Default Properties Files
4.3.3. Create a User With Administrator Privileges in the Default Realm Using the Default Properties Files
4.3.4. Create a User Belonging to Single Group Using Alternate Properties Files to Store the Information
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 EAP 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
5.4. Remoting
5.4.1. Configuration of Message Size in Remoting
5.4.2. Configure the Remoting Subsystem
6. Datasource Management
6.1. Introduction
6.1.1. About JDBC
6.1.2. JBoss EAP 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. Database Connection Validation
6.6.1. Configure Database Connection Validation Settings
6.7. Datasource Configuration
6.7.1. Datasource Parameters
6.7.2. Datasource Connection URLs
6.7.3. Datasource Extensions
6.7.4. View Datasource Statistics
6.7.5. Datasource Statistics
6.8. Example Datasources
6.8.1. Example PostgreSQL Datasource
6.8.2. Example PostgreSQL XA Datasource
6.8.3. Example MySQL Datasource
6.8.4. Example MySQL XA Datasource
6.8.5. Example Oracle Datasource
6.8.6. Example Oracle XA Datasource
6.8.7. Example Microsoft SQLServer Datasource
6.8.8. Example Microsoft SQLServer XA Datasource
6.8.9. Example IBM DB2 Datasource
6.8.10. Example IBM DB2 XA Datasource
6.8.11. Example Sybase Datasource
6.8.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 Subdeployment Module Isolation for All Deployments
7.3. Add a Module to All Deployments
7.4. Create a Custom Module
7.5. Define an External JBoss Module Directory
7.6. Reference
7.6.1. Included Modules
7.6.2. Dynamic Module Naming
8. Jsvc
8.1. Introduction
8.1.1. About Jsvc
8.1.2. Start and Stop JBoss EAP using Jsvc
9. Global Valves
9.1. About Valves
9.2. About Global Valves
9.3. About Authenticator Valves
9.4. Install a Global Valve
9.5. Configure a Global Valve
10. Application Deployment
10.1. About Application Deployment
10.2. Deploy with the Management Console
10.2.1. Manage Application Deployment in the Management Console
10.2.2. Enable a Deployed Application Using the Management Console
10.2.3. Disable a Deployed Application Using the Management Console
10.2.4. Undeploy an Application Using the Management Console
10.3. Deploy with the Management CLI
10.3.1. Manage Application Deployment in the Management CLI
10.3.2. Deploy an Application in a Standalone Server Using the Management CLI
10.3.3. Undeploy an Application in a Standalone Server Using the Management CLI
10.3.4. Deploy an Application in a Managed Domain Using the Management CLI
10.3.5. Undeploy an Application in a Managed Domain Using the Management CLI
10.4. Deploy with the HTTP API
10.4.1. Deploy an application using the HTTP API
10.5. Deploy with the Deployment Scanner
10.5.1. Manage Application Deployment in the Deployment Scanner
10.5.2. Deploy an Application to a Standalone Server Instance with the Deployment Scanner
10.5.3. Undeploy an Application from a Standalone Server Instance with the Deployment Scanner
10.5.4. Redeploy an Application to a Standalone Server Instance with the Deployment Scanner
10.5.5. Reference for Deployment Scanner Marker Files
10.5.6. Reference for Deployment Scanner Attributes
10.5.7. Configure the Deployment Scanner
10.5.8. Configure the Deployment Scanner with the Management CLI
10.5.9. Define a Custom Deployment Scanner
10.6. Deploy with Maven
10.6.1. Manage Application Deployment with Maven
10.6.2. Deploy an Application with Maven
10.6.3. Undeploy an Application with Maven
10.7. Control the order of Deployed Applications on JBoss EAP 6
10.8. Define a Custom Directory for Deployed Content
10.9. Deployment Descriptor Overrides
10.10. Rollout Plan
10.10.1. Rollout Plans
10.10.2. Operations with a Rollout Plan
10.10.3. Creating a Rollout Deployment Plan
11. Subsystem Configuration
11.1. Subsystem Configuration Overview
12. The Logging Subsystem
12.1. Introduction
12.1.1. Overview of Logging
12.1.2. Application Logging Frameworks Supported By JBoss LogManager
12.1.3. Bootup Logging
12.1.4. View Bootup Errors
12.1.5. About Garbage Collection Logging
12.1.6. Implicit Logging API Dependencies
12.1.7. Default Log File Locations
12.1.8. Filter Expressions for Logging
12.1.9. About Log Levels
12.1.10. Supported Log Levels
12.1.11. About Log Categories
12.1.12. About the Root Logger
12.1.13. About Log Handlers
12.1.14. Types of Log Handlers
12.1.15. About Log Formatters
12.1.16. Log Formatter Syntax
12.2. Configure Logging in the Management Console
12.3. Logging Configuration in the CLI
12.3.1. Configure the Root Logger with the CLI
12.3.2. Configure a Log Category in the CLI
12.3.3. Configure a Console Log Handler in the CLI
12.3.4. Configure a File Log Handler in the CLI
12.3.5. Configure a Periodic Log Handler in the CLI
12.3.6. Configure a Size Log Handler in the CLI
12.3.7. Configure a Periodic Size Rotating Log Handler in the CLI
12.3.8. Configure a Async Log Handler in the CLI
12.3.9. Configure a Custom Handler in the CLI
12.3.10. Configure a Syslog Handler in the CLI
12.3.11. Configure a Custom Log Formatter in the CLI
12.4. Per-deployment Logging
12.4.1. About Per-deployment Logging
12.4.2. Disable Per-deployment Logging
12.5. Logging Profiles
12.5.1. About Logging Profiles
12.5.2. Create a new Logging Profile using the CLI
12.5.3. Configuring a Logging Profile using the CLI
12.5.4. Specify a Logging Profile in an Application
12.5.5. Example Logging Profile Configuration
12.6. Logging Configuration Properties
12.6.1. Root Logger Properties
12.6.2. Log Category Properties
12.6.3. Console Log Handler Properties
12.6.4. File Log Handler Properties
12.6.5. Periodic Log Handler Properties
12.6.6. Size Log Handler Properties
12.6.7. Periodic Size Rotating Log Handler Properties
12.6.8. Async Log Handler Properties
12.7. Sample XML Configuration for Logging
12.7.1. Sample XML Configuration for the Root Logger
12.7.2. Sample XML Configuration for a Log Category
12.7.3. Sample XML Configuration for a Console Log Handler
12.7.4. Sample XML Configuration for a File Log Handler
12.7.5. Sample XML Configuration for a Periodic Log Handler
12.7.6. Sample XML Configuration for a Size Log Handler
12.7.7. Sample XML Configuration for a Periodic Size Rotating Log Handler
12.7.8. Sample XML Configuration for a Async Log Handler
13. Infinispan
13.1. About Infinispan
13.2. Clustering modes
13.3. Cache Containers
13.4. About Infinispan Statistics
13.5. Enable Infinispan Statistics Collection
13.5.1. Enable Infinispan Statistics Collection in the Startup Configuration File
13.5.2. Enable Infinispan Statistics Collection from the Management CLI
13.5.3. Verify Infinispan Statistics Collection is Enabled
13.6. Switching to Distributed Cache Mode for Web Session Replication
13.7. JGroups
13.7.1. About JGroups
13.8. JGroups Troubleshooting
13.8.1. Nodes do not form a cluster
13.8.2. Causes of missing heartbeats in FD
14. JVM
14.1. About JVM
14.1.1. About JVM Settings
14.1.2. Display the JVM Status in the Management Console
14.1.3. Configuring JVM
14.1.4. About the Java Security Manager
14.1.5. About Java Security Policies
14.1.6. Write a Java Security Policy
14.1.7. Run JBoss EAP 6 Within the Java Security Manager
14.1.8. IBM JDK and the Java Security Manager
14.1.9. Debug Security Manager Policies
15. Web Subsystem
15.1. Configure the Web Subsystem
15.2. Configure the HTTP Session Timeout
15.3. Servlet/HTTP Configuration
15.4. Replace the Default Welcome Web Application
15.5. System Properties in JBossWeb
15.6. About http-only Session Management Cookies
16. Web Services Subsystem
16.1. Configure Web Services Options
16.2. Overview of Handlers and Handler Chains
17. HTTP Clustering and Load Balancing
17.1. HTTP Server name conventions
17.2. Introduction
17.2.1. About High-Availability and Load Balancing Clusters
17.2.2. Components Which Can Benefit from High Availability
17.2.3. Overview of HTTP Connectors
17.2.4. Node types
17.3. Connector Configuration
17.3.1. Define Thread Pools for HTTP Connector in JBoss EAP 6
17.4. Web Server Configuration
17.4.1. About the Standalone Apache HTTP Server
17.4.2. HTTPD Variable Conventions
17.4.3. Install Apache HTTP Server in Red Hat Enterprise Linux 5, 6, and 7 (Zip)
17.4.4. Install Apache HTTP Server in Red Hat Enterprise Linux (RHEL) 5, 6, and 7 (RPM)
17.4.5. Manage Apache HTTP Server Service for Microsoft Windows Server Environment
17.4.6. mod_cluster Configuration on Apache HTTP Server
17.4.7. Use an External Web Server as the Web Front-end for JBoss EAP 6 Applications
17.4.8. Configure JBoss EAP 6 to Accept Requests From External Web Servers
17.5. Clustering
17.5.1. Use TCP Communication for the Clustering Subsystem
17.5.2. Configure the JGroups Subsystem to Use TCP
17.5.3. Disable Advertising for the mod_cluster Subsystem
17.5.4. Switch UDP to TCP for HornetQ Clustering
17.6. Web, HTTP Connectors, and HTTP Clustering
17.6.1. About the mod_cluster HTTP Connector
17.6.2. Configure the mod_cluster Subsystem
17.6.3. Install the mod_cluster Module Into Apache HTTP Server or JBoss Enterprise Web Server (Zip)
17.6.4. Install the mod_cluster Module Into Apache HTTP Server or JBoss Enterprise Web Server (RPM)
17.6.5. Configure Server Advertisement Properties for Your mod_cluster-enabled Web Server
17.6.6. Configure a mod_cluster Worker Node
17.6.7. Migrate Traffic between Clusters
17.6.8. Configure fail_on_status Parameter for mod_cluster
17.7. Apache mod_jk
17.7.1. About the Apache mod_jk HTTP Connector
17.7.2. Configure JBoss EAP 6 to Communicate with Apache mod_jk
17.7.3. Install the mod_jk Module Into the Apache HTTP Server (ZIP)
17.7.4. Install the mod_jk Module Into the Apache HTTP Server (RPM)
17.7.5. Configuration Reference for Apache mod_jk Workers
17.8. Apache mod_proxy
17.8.1. About the Apache mod_proxy HTTP Connector
17.8.2. Install the mod_proxy HTTP Connector into Apache HTTP Server
17.9. Microsoft ISAPI Connector
17.9.1. About the Internet Server API (ISAPI)
17.9.2. Download and Extract Webserver Connector Natives for Microsoft IIS
17.9.3. Configure Microsoft IIS to Use the ISAPI Connector
17.9.4. Configure the ISAPI Connector to Send Client Requests to JBoss EAP 6
17.9.5. Configure the ISAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers
17.10. Oracle NSAPI Connector
17.10.1. About the Netscape Server API (NSAPI)
17.10.2. Configure the NSAPI Connector on Oracle Solaris
17.10.3. Configure the NSAPI Connector to Send Client Requests to JBoss EAP 6
17.10.4. Configure the NSAPI Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers
18. Messaging
18.1. Introduction
18.1.1. HornetQ
18.1.2. Handling Slow HornetQ Consumers
18.1.3. Handling Blocking Calls During fail-over
18.1.4. Handling fail-over With Transactions
18.1.5. Handling fail-over With Non Transactional Sessions
18.1.6. Getting Notified of Connection Failure
18.1.7. About Java Messaging Service (JMS)
18.1.8. Supported Messaging Styles
18.2. Configuration of Transports
18.2.1. About Acceptors and Connectors
18.2.2. Configuring Netty TCP
18.2.3. Configuring Netty Secure Sockets Layer (SSL)
18.2.4. Configuring Netty HTTP
18.2.5. Configuring Netty Servlet
18.3. Dead Connection Detection
18.3.1. Closing Dead Connection Resources on the Server
18.3.2. Detecting Client Side Failure
18.4. Work with Large Messages
18.4.1. Work with Large Messages
18.4.2. Configuring HornetQ Large Messages
18.4.3. Configuring Parameters
18.5. Paging
18.5.1. About Paging
18.5.2. Page Files
18.5.3. Configuration of Paging Folder
18.5.4. Paging Mode
18.6. Diverts
18.6.1. Exclusive Divert
18.6.2. Non-exclusive Divert
18.7. The Client Classpath
18.8. Configuration
18.8.1. Configure the JMS Server
18.8.2. Configure JMS Address Settings
18.8.3. Temporary Queues and Runtime Queues
18.8.4. Last-Value Queues
18.8.5. Core and JMS Destinations
18.8.6. JMS Message Selectors
18.8.7. Configure Messaging with HornetQ
18.8.8. Enable Logging for HornetQ
18.8.9. Configuring HornetQ Core Bridge
18.8.10. Configuring JMS Bridge
18.8.11. Configure Delayed Redelivery
18.8.12. Configure Dead Letter Addresses
18.8.13. Configure Message Expiry Addresses
18.8.14. Flow Control
18.8.15. Reference for HornetQ Configuration Attributes
18.8.16. Set Message Expiry
18.9. PRE_ACKNOWLEDGE mode
18.9.1. Using PRE_ACKNOWLEDGE
18.9.2. Individual Acknowledge
18.10. Thread Management
18.10.1. Server-Side Thread Management
18.10.2. Client-Side Thread Management
18.11. Message Grouping
18.11.1. About Message Grouping
18.11.2. Using HornetQ Core API on Client Side
18.11.3. Configuring Server for Java Messaging Service (JMS) Clients
18.11.4. Clustered Grouping
18.11.5. Best Practices for Clustered Grouping
18.12. Duplicate Message Detection
18.12.1. About Duplicate Message Detection
18.12.2. Using Duplicate Message Detection for Sending Messages
18.12.3. Configuring Duplicate ID Cache
18.12.4. Using Duplicate Detection with Bridges and Cluster Connections
18.13. JMS Bridges
18.13.1. About Bridges
18.13.2. Create a JMS Bridge
18.14. Persistence
18.14.1. About Persistence in HornetQ
18.14.2. Import or Export the Journal Data
18.15. HornetQ Clustering
18.15.1. About Server Discovery
18.15.2. Broadcast Groups
18.15.3. Discovery Groups
18.15.4. Server Side Load Balancing
18.16. High Availability
18.16.1. High Availability Introduction
18.16.2. About HornetQ Shared Stores
18.16.3. About HornetQ Storage Configurations
18.16.4. About HornetQ Journal Types
18.16.5. Configuring HornetQ for Dedicated Topology with Shared Store
18.16.6. HornetQ Message Replication
18.16.7. Configuring the HornetQ Servers for Replication
18.16.8. About High-availability (HA) Failover
18.16.9. Deployments on HornetQ Backup Servers
18.16.10. HornetQ Failover Modes
18.16.11. Automatic Client Failover
18.16.12. Application-Level Failover
18.17. Performance Tuning
18.17.1. Tuning Persistence
18.17.2. Tuning JMS
18.17.3. Other Tunings
18.17.4. Tuning Transport Settings
18.17.5. Tuning the VM
18.17.6. Avoiding Anti-Patterns
19. Transaction Subsystem
19.1. Transaction Subsystem Configuration
19.1.1. Transactions Configuration Overview
19.1.2. Configure the Transaction Manager
19.1.3. Configure Your Datasource to Use JTA Transaction API
19.1.4. Configure an XA Datasource
19.1.5. About Transaction Log Messages
19.1.6. Configure Logging for the Transaction Subsystem
19.2. Transaction Administration
19.2.1. Browse and Manage Transactions
19.3. Transaction References
19.3.1. JBoss Transactions Errors and Exceptions
19.3.2. Limitations on JTA Transactions
19.4. ORB Configuration
19.4.1. About Common Object Request Broker Architecture (CORBA)
19.4.2. JacORB Configuration
19.4.3. Configure the ORB for JTS Transactions
19.5. JDBC Object Store Support
19.5.1. JDBC Store for Transactions
20. Mail subsystem
20.1. Use custom transports in mail subsystem
21. Enterprise JavaBeans
21.1. Introduction
21.1.1. Overview of Enterprise JavaBeans
21.1.2. Overview of Enterprise JavaBeans for Administrators
21.1.3. Enterprise Beans
21.1.4. Session Beans
21.1.5. Message-Driven Beans
21.2. Configuring Bean Pools
21.2.1. Bean Pools
21.2.2. Create a Bean Pool
21.2.3. Remove a Bean Pool
21.2.4. Edit a Bean Pool
21.2.5. Assign Bean Pools for Session and Message-Driven Beans
21.3. Configuring EJB Thread Pools
21.3.1. Enterprise Bean Thread Pools
21.3.2. Create a Thread Pool
21.3.3. Remove a Thread Pool
21.3.4. Edit a Thread Pool
21.4. Configuring Session Beans
21.4.1. Session Bean Access Timeout
21.4.2. Set Default Session Bean Access Timeout Values
21.4.3. Session Bean Transaction Timeout
21.4.4. Configure Stateful Session Bean Cache
21.5. Configuring Message-Driven Beans
21.5.1. Set Default Resource Adapter for Message-Driven Beans
21.6. Configuring the EJB3 Timer Service
21.6.1. EJB3 Timer Service
21.6.2. Configure the EJB3 Timer Service
21.7. Configuring the EJB Asynchronous Invocation Service
21.7.1. EJB3 Asynchronous Invocation Service
21.7.2. Configure the EJB3 Asynchronous Invocation Service Thread Pool
21.8. Configuring the EJB3 Remote Invocation Service
21.8.1. EJB3 Remote Service
21.8.2. Configure the EJB3 Remote Service
21.9. Configuring EJB 2.x Entity Beans
21.9.1. EJB Entity Beans
21.9.2. Container-Managed Persistence
21.9.3. Enable EJB 2.x Container-Managed Persistence
21.9.4. Configure EJB 2.x Container-Managed Persistence
21.9.5. CMP Subsystem Properties for HiLo Key Generators
22. Java Connector Architecture (JCA)
22.1. Introduction
22.1.1. About the Java EE Connector API (JCA)
22.1.2. Java Connector Architecture (JCA)
22.1.3. Resource Adapters
22.2. Configure the Java Connector Architecture (JCA) Subsystem
22.3. Deploy a Resource Adapter
22.4. Configure a Deployed Resource Adapter
22.5. Resource Adapter Descriptor Reference
22.6. View Defined Connection Statistics
22.7. Resource Adapter Statistics
22.8. Deploy the WebSphere MQ Resource Adapter
22.9. Install JBoss Active MQ Resource Adapter
22.10. Configure a Generic JMS Resource Adapter for Use with a Third-party JMS Provider
22.11. Configuring the HornetQ JCA Adapter for Remote Connections
23. Hibernate Search
23.1. Getting Started with Hibernate Search
23.1.1. About Hibernate Search
23.1.2. Overview
23.1.3. About the Index Manager
23.1.4. About the Directory Provider
23.1.5. About the Worker
23.1.6. Back End Setup and Operations
23.1.7. Reader Strategies
23.2. Configuration
23.2.1. Minimum Configuration
23.2.2. Configuring the IndexManager
23.2.3. DirectoryProvider Configuration
23.2.4. Sharding Indexes
23.2.5. Worker Configuration
23.2.6. Tuning Lucene Indexing
23.2.7. LockFactory Configuration
23.2.8. Exception Handling Configuration
23.2.9. Index Format Compatibility
23.2.10. Disable Hibernate Search
23.3. Monitoring
23.3.1. Monitoring
24. Deploy JBoss EAP 6 on Amazon EC2
24.1. Introduction
24.1.1. About Amazon EC2
24.1.2. About Amazon Machine Instances (AMIs)
24.1.3. About JBoss Cloud Access
24.1.4. JBoss Cloud Access Features
24.1.5. Supported Amazon EC2 Instance Types
24.1.6. Supported Red Hat AMIs
24.2. Deploying JBoss EAP 6 on Amazon EC2
24.2.1. Overview of Deploying JBoss EAP 6 on Amazon EC2
24.3. Non-clustered JBoss EAP 6
24.3.1. About Non-clustered Instances
24.4. Non-clustered Instances
24.4.1. Launch a Non-clustered JBoss EAP 6 Instance
24.4.2. Deploy an Application on a non-clustered JBoss EAP 6 Instance
24.4.3. Test the Non-clustered JBoss EAP 6 Instance
24.5. Non-clustered Managed Domains
24.5.1. Launch an Instance to Serve as a Domain Controller
24.5.2. Launch One or More Instances to Serve as Host Controllers
24.5.3. Test the Non-Clustered JBoss EAP 6 Managed Domain
24.5.4. Configuring Domain Controller Discovery and Failover on Amazon EC2
24.6. Clustered JBoss EAP 6
24.6.1. About Clustered Instances
24.6.2. About Virtual Private Clouds
24.6.3. Create a Virtual Private Cloud (VPC)
24.6.4. Launch an Apache HTTP Server Instance to Serve as a mod_cluster Proxy and a NAT Instance for the VPC
24.6.5. Configure the VPC Private Subnet Default Route
24.6.6. About Identity and Access Management (IAM)
24.6.7. Configure IAM Setup
24.6.8. About the S3 Bucket
24.6.9. Configure S3 Bucket Setup
24.7. Clustered Instances
24.7.1. Launch Clustered JBoss EAP 6 AMIs
24.7.2. Test the Clustered JBoss EAP 6 Instance
24.8. Clustered Managed Domains
24.8.1. Launch an Instance to Serve as a Cluster Domain Controller
24.8.2. Launch One or More Instances to Serve as Cluster Host Controllers
24.8.3. Test the Clustered JBoss EAP 6 Managed Domain
24.9. Establishing Monitoring with JBoss Operations Network (JON)
24.9.1. About AMI Monitoring
24.9.2. About Connectivity Requirements
24.9.3. About Network Address Translation (NAT)
24.9.4. About Amazon EC2 and DNS
24.9.5. About Routing in EC2
24.9.6. About Terminating and Restarting with JON
24.9.7. Configure an Instance to Register with JBoss Operations Network
24.10. User Script Configuration
24.10.1. Permanent Configuration Parameters
24.10.2. Custom Script Parameters
24.11. Troubleshooting
24.11.1. About Troubleshooting Amazon EC2
24.11.2. Diagnostic Information
25. Externalize Sessions
25.1. Externalize HTTP Session from JBoss EAP to JBoss Data Grid
A. Supplemental References
A.1. Download Files from the Red Hat Customer Portal
A.2. Configure the Default Java Development Kit on Red Hat Enterprise Linux
A.3. Management Interface Audit Logging Reference
B. Revision History

Chapter 1. Introduction

1.1. About Red Hat JBoss Enterprise Application Platform 6

Red Hat JBoss Enterprise Application Platform 6 (JBoss EAP 6) is a middleware platform built on open standards and compliant with the Java Enterprise Edition 6 specification. It integrates JBoss Application Server 7 with high-availability clustering, messaging, distributed caching, and other technologies.
JBoss EAP 6 includes a new, modular structure that allows service enabling only when required, improving startup speed.
The Management Console and Management Command Line Interface make editing XML configuration files unnecessary and add the ability to script and automate tasks.
In addition, JBoss EAP 6 includes APIs and development frameworks for quickly developing secure and scalable Java EE applications.

1.2. Features of JBoss EAP 6

Table 1.1. JBoss EAP 6 Features

Feature Description
Java Certification Java Enterprise Edition 6 Full Profile and Web Profile certified.
Managed Domain
  • Centralized management of multiple server instances and physical hosts, while a standalone server allows for a single server instance.
  • Per-server group management of configuration, deployment, socket bindings, modules, extensions and system properties.
  • Centralized and simplified management of application security (including security domains).
Management Console and Management CLI New domain or standalone server management interfaces. XML configuration file editing is no longer required. The Management CLI also includes a batch mode that can script and automate management tasks.
Simplified directory layout The modules directory now contains all application server modules. The common and server-specific lib directories are deprecated. The domain and standalone directories contain the artifacts and configuration files for domain and standalone deployments respectively.
Modular class loading mechanism Modules are loaded and unloaded on demand. This improves performance, has security benefits and reduces start-up and restart times.
Streamlined Data source management Database drivers are deployed like other services. In addition, datasources are created and managed directly in the Management Console or Management CLI.
Reduced and more efficient resource use JBoss EAP 6 uses fewer system resources and uses them more efficiently than previous versions. Among other benefits, JBoss EAP 6 starts and stops faster than JBoss EAP 5.

1.3. About JBoss EAP 6 Operating Modes

JBoss EAP 6 provides two operating modes for JBoss EAP 6 instances: standalone server or managed domain.
The two modes differ in how servers are managed, not in their capacity to service end-user requests. It is important to note that the high-availability (HA) cluster functionality is available via either operating mode. A group of standalone servers can be configured to form an HA cluster.

1.4. About Standalone Servers

Standalone server mode is an independent process and is analogous to the only running mode available in previous JBoss EAP versions.
A JBoss EAP 6 instance running as a standalone server is a single instance only but can optionally run in a clustered configuration.

1.5. About Managed Domains

A managed domain with one domain controller, three host controllers, and three server groups. Servers are members of server groups, and may be located on any of the host controllers in the domain.

Figure 1.1. Graphical Representation of a Managed Domain

The managed domain operating mode allows for management of multiple JBoss EAP 6 instances from a single control point.
Centrally managed JBoss EAP 6 server collections are known as members of a domain. All JBoss EAP 6 instances in a domain share a common management policy.
A domain consists of one domain controller, one or more host controller(s), and zero or more server groups per host.
A domain controller is the central point from which the domain is controlled. It ensures that each server is configured according to the management policy of the domain. The domain controller is also a host controller.
A host controller is a physical or virtual host on which the domain.sh or domain.bat script is run. Host controllers are configured to delegate domain management tasks to the domain controller.
The host controller on each host interacts with the domain controller to control the lifecycle of the application server instances running on its host and to assist the domain controller to manage them. Each host can contain multiple server groups.
A server group is a set of server instances which have JBoss EAP 6 installed on them and are managed and configured as one. The domain controller manages the configuration of and applications deployed onto server groups. Consequently, each server in a server group shares the same configuration and deployments.
It is possible for a domain controller, a single host controller, and multiple servers to run within the same JBoss EAP 6 instance, on the same physical system.
Host controllers are tied to specific physical (or virtual) hosts. You can run multiple host controllers on the same hardware if you use different configurations, ensuring their ports and other resources do not conflict.

1.6. About the Domain Controller

A domain controller is the JBoss EAP 6 server instance that acts as a central management point for a domain. One host controller instance is configured to act as a domain controller.
The primary responsibilities of the domain controller are:
  • Maintain the domain's central management policy.
  • Ensure all host controllers are aware of its current contents.
  • Assist the host controllers in ensuring that all running JBoss EAP 6 instances are configured in accordance with this policy.
By default, the central management policy is stored in the domain/configuration/domain.xml file. This file is in the unzipped JBoss EAP 6 installation file, on the domain controller's host's filesystem.
A domain.xml file must be located in the domain/configuration/ directory of the host controller set to run as the domain controller. This file is not mandatory for installations on host controllers that are not meant to run as a domain controller. The presence of a domain.xml file on such a server does no harm, however.
The domain.xml file contains the profile configurations that can be run on the server instances in a domain. A profile configuration includes the detailed settings of the various subsystems that comprise a profile. The domain configuration also includes the definition of socket groups and the server group definitions.

1.7. About Domain Controller Discovery and Failover

When setting up a managed domain, each host controller must be configured with information needed to contact the domain controller. In JBoss EAP 6, each host controller can be configured with multiple options for finding the domain controller. Host controllers iterate through the list of options until one succeeds.
This allows host controllers to be pre-configured with contact information for a backup domain controller. A backup host controller can be promoted to master if there is a problem with the primary domain controller, allowing host controllers to automatically fail over to the new master once it’s been promoted.
The following is an example of how to configure a host controller with multiple options for finding the domain controller.

Example 1.1. Host controller configured with multiple domain controller options

<domain-controller>  
    <remote security-realm="ManagementRealm">  
          <discovery-options>  
              <static-discovery name="primary" host="172.16.81.100" port="9999"/>  
              <static-discovery name="backup" host="172.16.81.101" port="9999"/>  
          </discovery-options>  
    </remote>  
</domain-controller>
A static discovery option includes the following mandatory attributes:

name
The name for this domain controller discovery option
host
The remote domain controller's host name.
port
The remote domain controller's port.
In the example above, the first discovery option is the one expected to succeed. The second can be used in failover situations.
If a problem arises with the primary domain controller, a host controller that was started with the --backup option can be promoted to act as the domain controller.

Note

Starting a host controller with the --backup option will cause that controller to maintain a local copy of the domain configuration. This configuration will be used if the host controller is reconfigured to act as the domain controller.

Procedure 1.1. Promoting a host controller to be the domain controller

  1. Ensure the original domain controller has, or is, stopped.
  2. Use the Management CLI to connect to the host controller that is to become the new domain controller.
  3. Execute the following command to configure the host controller to act as the new domain controller.
    /host=HOST_NAME:write-local-domain-controller
  4. Execute the following command to reload the host controller.
    reload --host=HOST_NAME
The host controller chosen in step 2 will now act as the domain controller.

1.8. About Host Controller

A host controller is launched when the domain.sh or domain.bat script is run on a host.
The primary responsibility of a host controller is server management. It delegates domain management tasks and is responsible for starting and stopping the individual application server processes that run on its host.
It interacts with the domain controller to help manage the communication between the servers and the domain controller. Multiple host controllers of a domain can interact with only a single domain controller. Hence, all the host controllers and server instances running on a single domain mode have a single domain controller and must belong to the same domain.
By default each host controller reads its configuration from the domain/configuration/host.xml file located in the unzipped JBoss EAP 6 installation file on its host's filesystem. The host.xml file contains the following configuration information that is specific to the particular host:
  • The names of the JBoss EAP 6 instances meant to run from this installation.
  • Any of the following configurations:
    • How the host controller contacts the domain controller to register itself and access the domain configuration.
    • How to find and contact a remote domain controller.
    • That the host controller is to act as the domain controller
  • Configurations specific to the local physical installation. For example, named interface definitions declared in domain.xml can be mapped to an actual machine-specific IP address in host.xml. And abstract path names in domain.xml can be mapped to actual filesystem paths in host.xml.

1.9. About Server Groups

A server group is a collection of server instances that are managed and configured as one. In a managed domain, every application server instance belongs to a server group, even if it is the only member. The server instances in a group share the same profile configuration and deployed content.
A domain controller and a host controller enforce the standard configuration on all server instances of every server group in its domain.
A domain can consist of multiple server groups. Different server groups can be configured with different profiles and deployments. A domain can be configured with different server tiers providing different services, for example.
Different server groups can also have the same profile and deployments. This can, for example, allow for rolling application upgrades where the application is upgraded on one server group and then updated on a second server group, avoiding a complete service outage.
The following is an example of a server group definition:

Example 1.2. Server group definition

<server-group name="main-server-group" profile="default">
 <socket-binding-group ref="standard-sockets"/>
  <deployments>
   <deployment name="foo.war_v1" runtime-name="foo.war"/>
   <deployment name="bar.ear" runtime-name="bar.ear"/>
  </deployments>
</server-group>
A server group includes the following mandatory attributes:
  • name: the server group name.
  • profile: the server group profile name.
  • socket-binding-group: the default socket binding group used for servers in the group. This name can be overridden on a per-server basis in host.xml. However, this is a mandatory element for every server group and the domain can not start if it is missing.
A server group includes the following optional attributes:
  • deployments: the deployment content to be deployed on the servers in the group.
  • system-properties: the system properties to be set on servers in the group
  • jvm: the default JVM settings for all servers in the group. The host controller merges these settings with any other configuration provided in host.xml to derive the settings used to launch the server's JVM.
  • socket-binding-port-offset: the default offset to be added to the port values given by the socket binding group.
  • management-subsystem-endpoint: set to true to have servers belonging to the server group connect back to the host controller using the endpoint from their Remoting subsystem (the Remoting subsystem must be present for this to work).

1.10. About JBoss EAP 6 Profiles

The concept of profiles that was used in previous versions of JBoss EAP is no longer used. JBoss EAP 6 now uses a small number of configuration files to hold all information about its configuration.
Modules and drivers are now loaded on an as-needed basis. Consequently the concept of a default profile - used in previous versions of JBoss EAP 6 to make the server start more efficiently - does not apply.
At deployment time, module dependencies are determined, ordered, resolved by the server or domain controller, and loaded in the correct order. Modules are unloaded when no deployment needs them any longer.
It is possible to disable modules or unload drivers and 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.

1.11. Manage Servers of Different Versions

Note

You must have the latest release of JBoss EAP is functioning as the domain controller in order to manage different versions of JBoss EAP servers.
  • JBoss EAP schema uses different versions. Hence, JBoss EAP domain controller of a higher version must not have issues controlling a JBoss EAP host of a lower version, but the domain.xml must be the oldest of all the versions in use.
  • If there is a cluster, all member servers of the cluster must belong to the same version of JBoss EAP.
  • On every host in the domain, there are several Java processes like Process Controller, Host Controller and managed servers. These Java processes must be launched from the same installation of JBoss EAP, hence have the same version.

Warning

However, there is a minor incompatibility when the domain controller from JBoss EAP 6.3 manages slaves from JBoss EAP 6.2 or below that must be corrected: the [named-formatter] attribute is not understood in the target model version and must be replaced with older attributes. For more details, refer to https://access.redhat.com/solutions/1238073

Chapter 2. Application Server Management

2.1. JBoss EAP Documentation Conventions

All instances of EAP_HOME in this guide refer to the JBoss EAP root installation directory, which depends on the installation method you used.

Zip Installation Method
EAP_HOME refers to the directory in which the JBoss EAP ZIP file was extracted.
Installer Method
EAP_HOME refers to the directory in which you chose to install JBoss EAP.
RPM Installation Method
EAP_HOME refers to the directory /usr/share/jbossas.

Note

The notation EWS_HOME is used to refer to JBoss EWS installation locations following the same conventions outlined above for JBoss EAP.

2.2. Start and Stop JBoss EAP 6

2.2.1. Start JBoss EAP 6

JBoss EAP runs in one of two modes, Standalone Server or Managed Domain, and is supported on two platforms, Red Hat Enterprise Linux and Microsoft Windows Server. The specific command to start JBoss EAP depends on the underlying platform and the desired mode.

Table 2.1. Commands to start JBoss EAP

Operating System Standalone Server Managed Domain
Red Hat Enterprise Linux EAP_HOME/bin/standalone.sh EAP_HOME/bin/domain.sh
Microsoft Windows Server EAP_HOME\bin\standalone.bat EAP_HOME\bin\domain.bat

2.2.2. Start JBoss EAP 6 as a Standalone Server

Summary
This topic covers the steps to start JBoss EAP 6 as a Standalone Server.

Procedure 2.1. Start the Platform Service as a Standalone Server

  1. For Red Hat Enterprise Linux.

    Run the command: EAP_HOME/bin/standalone.sh
  2. For Microsoft Windows Server.

    Run the command: EAP_HOME\bin\standalone.bat
  3. Optional: Specify additional parameters.

    To list all available parameters for the start-up scripts, use the -h parameter.
Result
The JBoss EAP 6 Standalone Server instance starts.

2.2.3. Running Multiple JBoss EAP Standalone Servers on a Single Machine

Summary
This topic describes the steps for running multiple JBoss EAP Standalone servers on a single machine.

Procedure 2.2. Run multiple instances of JBoss EAP standalone servers on a single machine

  1. Create a copy of the EAP_HOME/standalone/ directory directly under EAP_HOME/ for each standalone server. For example, to create a directory for standalone servers node1 and node2, type the following commands.
    $ cd EAP_HOME
    $ cp -a ./standalone ./node1 
    $ cp -a ./standalone ./node2
  2. Start each JBoss EAP standalone instance by specifying the node name, IP address, server directory, optional server configuration file, and optional port offset. The command uses the following syntax:
    $ ./bin/standalone.sh -Djboss.node.name=UNIQUE_NODENAME -Djboss.server.base.dir=EAP_HOME/NODE_DIRECTORY -b IP_ADDRESS -bmanagement MGMT_IP_ADDRESS --server-config=SERVER_CONFIGURATION_FILE -Djboss.socket.binding.port-offset=PORT_OFFSET
    1. This example starts node1
      $ cd EAP_HOME
      $ ./bin/standalone.sh -Djboss.node.name=node1 -Djboss.server.base.dir=EAP_HOME/node1 -b 10.10.10.10 -bmanagement 127.0.0.1
      
    2. This example to start node2 depends on whether the machine supports multiple IP addresses.
      • If the machine supports multiple IP addresses, the following command is to be used.
        $ cd EAP_HOME
        $ ./bin/standalone.sh -Djboss.node.name=node2 -Djboss.server.base.dir=EAP_HOME/node2 -b 10.10.10.40 -bmanagement 127.0.0.40
        
      • If the machine does not support multiple IP addresses, you must specify a jboss.socket.binding.port-offset property to avoid a port conflict.
        $ cd EAP_HOME
        $ ./bin/standalone.sh -Djboss.node.name=node2 -Djboss.server.base.dir=EAP_HOME/node2 -b 10.10.10.10 -bmanagement 127.0.0.1 -Djboss.socket.binding.port-offset=100
        

Note

If you would like to manage two nodes at once or two nodes that have the same configuration, you are recommended to run them in a managed domain instead of running a standalone server.

2.2.4. Start JBoss EAP 6 as a Managed Domain

Order of Operations
The domain controller must be started before any slave servers in any server groups in the domain. Use this procedure first on the domain controller, and then on each associated host controller and each other host associated with the domain.

Procedure 2.3. Start the Platform Service as a Managed Domain

  1. For Red Hat Enterprise Linux.

    Run the command: EAP_HOME/bin/domain.sh
  2. For Microsoft Windows Server.

    Run the command: EAP_HOME\bin\domain.bat
  3. Optional: Pass additional parameters to the start-up script.

    To list all available parameters for the start-up scripts, use the -h parameter.
Result
The JBoss EAP 6 Managed Domain instance starts.

2.2.5. Configure the Name of a Host in a Managed Domain

Summary
Every host running in a managed domain must have a unique host name. To ease administration and allow for the use of the same host configuration files on multiple hosts, the server uses the following precedence for determining the host name.
  1. If set, the host element name attribute in the host.xml configuration file.
  2. The value of the jboss.host.name system property.
  3. The value that follows the final period (".") character in the jboss.qualified.host.name system property, or the entire value if there is no final period (".") character.
  4. The value that follows the period (".") character in the HOSTNAME environment variable for POSIX-based operating systems, the COMPUTERNAME environment variable for Microsoft Windows, or the entire value if there is no final period (".") character.
For information about how to set environment variables, see the documentation for your operating system. For information about how to set system properties, see Section 3.5.11, “Configure System Properties Using the Management CLI”.
This topic describes how set the name of the host in the configuration file, using either a system property or a hard-coded name.

Procedure 2.4. Configure the Host Name Using a System Property

  1. Open the host configuration file for editing, for example, host.xml.
  2. Find the host element in the file, for example:
    <host name="master" xmlns="urn:jboss:domain:1.6">
  3. If it is present, remove the name="HOST_NAME" attribute declaration. The host element should now look like the following example.
    <host xmlns="urn:jboss:domain:1.6">
  4. Start the server passing the -Djboss.host.name argument, for example:
    -Djboss.host.name=HOST_NAME

Procedure 2.5. Configure the Host Name Using a Specific Name

  1. Start the JBoss EAP slave host using the following syntax:
    bin/domain.sh --host-config=HOST_FILE_NAME
    For example:
    bin/domain.sh --host-config=host-slave01.xml
  2. Launch the Management CLI.
  3. Use the following syntax to replace the host name:
    /host=EXISTING_HOST_NAME:write-attribute(name="name",value=UNIQUE_HOST_NAME)
    For example:
    /host=master:write-attribute(name="name",value="host-slave01")
    You should see the following result.
     "outcome" => "success"
    This modifies the host name attribute in the host-slave01.xml file as follows:
    <host name="host-slave01" xmlns="urn:jboss:domain:1.6">
  4. You must reload the server configuration using the old host name to complete the process
    reload --host=EXISTING_HOST_NAME
    For example:
    reload --host=master

2.2.6. Create Managed Domain on Two Machines

Note

You may need to configure your firewall to run this example.
You can create managed domain on two machines, wherein one machine is a domain controller and the other machine is a host. For more information, see Section 1.6, “About the Domain Controller”.
  • IP1 = IP address of the domain controller (Machine 1)
  • IP2 = IP address of the host (Machine 2)

Procedure 2.6. Create managed domain on two machines

  1. On Machine 1

    1. Use the add-user.sh script to add management user. For example, slave01, so the host can authenticate the domain controller. Note the SECRET_VALUE from the add-user output.
    2. Start domain with host-master.xml config file, which is preconfigured for dedicated domain controller.
    3. Use -bmanagement=$IP1 to make domain controller visible to other machines.
      EAP_HOME/bin/domain.sh --host-config=host-master.xml -bmanagement=$IP1
  2. On Machine 2

    1. Update EAP_HOME/domain/configuration/host-slave.xml file with user credentials.
      	<?xml version='1.0' encoding='UTF-8'?>
              <host xmlns="urn:jboss:domain:1.6" name="slave01">   
              <!-- add user name here -->
               <management>
                  <security-realms>
                     <security-realm name="ManagementRealm">
                        <server-identities>
                          <secret value="$SECRET_VALUE" />   
                          <!-- use secret value from add-user.sh output-->
                        </server-identities> 
                        ...
    2. Start host.
      EAP_HOME/bin/domain.sh --host-config=host-slave.xml  -Djboss.domain.master.address=$IP1 -b=$IP2
  3. Now we can manage the domain.

    via CLI:
    EAP_HOME/bin/jboss-cli.sh -c --controller=$IP1
    
    via Web Console:
    http://$IP1:9990
    
    Access the server index page:
    http://$IP2:8080/
    http://$IP2:8230/
    

2.2.7. Create Managed Domain on a Single Machine

Multiple host controllers can be run on a single machine by using the jboss.domain.base.dir property.

Procedure 2.7. Run Multiple Host Controllers on a Single Machine

  1. Copy the EAP_HOME/domain directory for the domain controller.
    cp -r EAP_HOME/domain /path/to/domain1
  2. Copy the EAP_HOME/domain directory for a host controller.
    cp -r EAP_HOME/domain /path/to/host1
  3. Start the domain controller using /path/to/domain1.
    EAP_HOME/bin/domain.sh --host-config=host-master.xml -Djboss.domain.base.dir=/path/to/domain1
  4. Start the host controller using /path/to/host1.
    EAP_HOME/bin/domain.sh --host-config=host-slave.xml -Djboss.domain.base.dir=/path/to/host1 -Djboss.domain.master.address=IP_ADDRESS -Djboss.management.native.port=PORT
Result
Each instance started in this manner will share the rest of the resources in the base installation directory (i.e. EAP_HOME/modules/), but use the domain configuration from the directory specified by jboss.domain.base.dir.

2.2.8. Start JBoss EAP 6 with an Alternative Configuration

If you do not specify a configuration file, the server starts with the default file.
You can also specify a configuration manually. This process varies depending on whether you are using a Managed Domain or Standalone Server, and operating system.

Prerequisites

  • Before using an alternative configuration file, prepare it using the default configuration as a template.
  • For Managed Domains, alternative configuration files are stored in the EAP_HOME/domain/configuration/ directory.
  • For Standalone Servers, alternative configuration files are stored in the EAP_HOME/standalone/configuration/ directory.

Note

Example configurations are included in the EAP_HOME/docs/examples/configs/ directory. Use these examples to enable features such as clustering or the Transactions XTS API.
Start the Instance with an Alternative Configuration
Standalone server
For a Standalone Server, provide the configuration filename using the --server-config switch. The configuration file must be in the EAP_HOME/standalone/configuration/ directory, and you must specify the file path relative to this directory.

Example 2.1. Using an Alternate Configuration file for a Standalone Server in Red Hat Enterprise Linux

[user@host bin]$ ./standalone.sh --server-config=standalone-alternate.xml
This example uses the EAP_HOME/standalone/configuration/standalone-alternate.xml configuration file.

Example 2.2. Using an Alternate Configuration file for a Standalone Server in Microsoft Windows Server

C:\EAP_HOME\bin> standalone.bat --server-config=standalone-alternate.xml
This example uses the EAP_HOME\standalone\configuration\standalone-alternative.xml configuration file.
Managed Domain
For a Managed Domain, provide the configuration filename using the --domain-config switch. The configuration file must be in the EAP_HOME/domain/configuration/ directory, and you need to specify the path relative to that 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
This example uses the EAP_HOME/domain/configuration/domain-alternate.xml configuration file.

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

This example uses the EAP_HOME\domain\configuration\domain-alternate.xml configuration file.

2.2.9. Stop JBoss EAP 6

The way that you stop JBoss EAP 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

For information on how to stop a server or server group in a Managed Domain see Section 2.3.3, “Stop a Server Using the Management Console”. For information on how to stop a server using the Management CLI, see Section 2.3.1, “Start and Stop Servers Using the Management CLI”.

Procedure 2.8. Stop an instance of JBoss EAP 6

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

    Press Ctrl-C in the terminal where JBoss EAP 6 is running.

Procedure 2.9. Stop an instance which was started as an operating system service.

Depending on the 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 the script.
    • Microsoft Windows Server

      In Microsoft Windows, use the net service command, or stop the service from the Services applet in the Control Panel.

Procedure 2.10. Stop an instance which is running in the background (Red Hat Enterprise Linux)

  1. Obtain the process ID (PID) of the process:
    • If only a single instance is running (standalone mode)

      Either of the following commands will return the PID of a single instance of JBoss EAP 6:
      • pidof java
      • jps
        (The jps command will return an ID for two processes; one for jboss-modules.jar and one for jps itself. Use the ID for jboss-modules.jar to stop the EAP instance)
    • If multiple EAP instances are running (domain mode)

      Identifying the correct process to end if more than one instance of EAP is running requires more comprehensive commands be used.
      • The jps command can be used in verbose mode to provide more information about the java processes it finds.
        Below is an abridged output from a verbose jps command identifying the different EAP processes running by PID and role:
        $ jps -v
        12155 jboss-modules.jar -D[Server:server-one] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1303m 
        ...
        
        12196 jboss-modules.jar -D[Server:server-two] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1303m 
        ...
        
        12096 jboss-modules.jar -D[Host Controller] -Xms64m -Xmx512m -XX:MaxPermSize=256m 
        ...
        
        11872 Main -Xms128m -Xmx750m -XX:MaxPermSize=350m -XX:ReservedCodeCacheSize=96m -XX:+UseCodeCacheFlushing 
        ...
        
        11248 jboss-modules.jar -D[Standalone] -XX:+UseCompressedOops -verbose:gc 
        ...
        
        12892 Jps 
        ...
        
        12080 jboss-modules.jar -D[Process Controller] -Xms64m -Xmx512m -XX:MaxPermSize=256m 
        ...
        
      • The ps aux command can also be used to return information about multiple EAP instances.
        Below is an abridged output from a verbose ps aux command identifying the different EAP processes running by PID and role:
        $ ps aux | grep java
        username 12080  0.1  0.9 3606588 36772 pts/0   Sl+  10:09   0:01 /path/to/java -D[Process Controller] -server -Xms128m -Xmx128m -XX:MaxPermSize=256m 
        ...
        
        username 12096  1.0  4.1 3741304 158452 pts/0  Sl+  10:09   0:13 /path/to/java -D[Host Controller] -Xms128m -Xmx128m -XX:MaxPermSize=256m 
        ...
        
        username 12155  1.7  8.9 4741800 344224 pts/0  Sl+  10:09   0:22 /path/to/java -D[Server:server-one] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1000m -Xmx1000m -server -
        ...
        
        username 12196  1.8  9.4 4739612 364436 pts/0  Sl+  10:09   0:22 /path/to/java -D[Server:server-two] -XX:PermSize=256m -XX:MaxPermSize=256m -Xms1000m -Xmx1000m -server 
        ...
        
      In the above examples, the Process Controller processes are the processes to stop in order to stop the entire domain.
      The grep utility can be used with either of these commands to identify the Process Controller:
      jps -v | grep "Process Controller"
      ps aux | grep "Process Controller"
  2. Send the process the TERM signal, by running kill PID, where PID is the process ID identified by one of the commands above.
Result
Each of these alternatives shuts JBoss EAP 6 down cleanly so that data is not lost.

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

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

Table 2.2. Runtime Switches and Arguments

Argument or Switch Mode Description
--admin-only Standalone 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.
--admin-only Domain Set the host controller's running type to ADMIN_ONLY causing it to open administrative interfaces and accept management requests but not start servers or, if this host controller is the master for the domain, accept incoming connections from slave host controllers.
-b=<value>, -b <value> Standalone, Domain Set system property jboss.bind.address, which is used in configuring the bind address for the public interface. This defaults to 127.0.0.1 if no value is specified. See the -b<interface>=<value> entry for setting the bind address for other interfaces.
-b<interface>=<value> Standalone, Domain Set system property jboss.bind.address.<interface> to the given value. For example, -bmanagement=IP_ADDRESS
--backup Domain Keep a copy of the persistent domain configuration even if this host is not the Domain Controller.
-c=<config>, -c <config> Standalone Name of the server configuration file to use. The default is standalone.xml.
-c=<config>, -c <config> Domain Name of the server configuration file to use. The default is domain.xml.
--cached-dc Domain If the host is not the Domain Controller and cannot contact the Domain Controller at boot, boot using a locally cached copy of the domain configuration.
--debug [<port>] Standalone Activate debug mode with an optional argument to specify the port. Only works if the launch script supports it.
-D<name>[=<value>] Standalone, Domain Set a system property.
--domain-config=<config> Domain Name of the server configuration file to use. The default is domain.xml.
-h, --help Standalone, Domain Display the help message and exit.
--host-config=<config> Domain Name of the host configuration file to use. The default is host.xml.
--interprocess-hc-address=<address> Domain Address on which the host controller should listen for communication from the process controller.
--interprocess-hc-port=<port> Domain Port on which the host controller should listen for communication from the process controller.
--master-address=<address> Domain Set system property jboss.domain.master.address to the given value. In a default slave Host Controller config, this is used to configure the address of the master Host Controller.
--master-port=<port> Domain Set system property jboss.domain.master.port to the given value. In a default slave Host Controller config, this is used to configure the port used for native management communication by the master Host Controller.
--read-only-server-config=<config> Standalone Name of the server configuration file to use. This differs from --server-config and -c in that the original file is never overwritten.
--read-only-domain-config=<config> Domain Name of the domain configuration file to use. This differs from --domain-config and -c in that the initial file is never overwritten.
--read-only-host-config=<config> Domain Name of the host configuration file to use. This differs from --host-config in that the initial file is never overwritten.
-P=<url>, -P <url>, --properties=<url> Standalone, Domain Load system properties from the given URL.
--pc-address=<address> Domain Address on which the process controller listens for communication from processes it controls.
--pc-port=<port> Domain Port on which the process controller listens for communication from processes it controls.
-S<name>[=<value>] Standalone Set a security property.
--server-config=<config> Standalone Name of the server configuration file to use. The default is standalone.xml.
-u=<value>, -u <value> Standalone, Domain Set system property jboss.default.multicast.address, which is used in configuring the multicast address in the socket-binding elements in the configuration files. This defaults to 230.0.0.4 if no value is specified.
-v, -V, --version Standalone, Domain Display the application server version and exit.

Warning

The configuration files that ship with JBoss EAP 6 are set up to handle the behavior of the switches (i.e. -b, -u). If you change your configuration files to no longer use the system property controlled by the switch, then adding it to the launch command will have no effect.

2.3. Start and Stop Servers

2.3.1. Start and Stop Servers Using the Management CLI

Servers can be started and stopped using the Management CLI or Management Console. Both tools can control a single Standalone Server instance or manage multiple servers across a Managed Domain deployment.
To use the Management Console, refer to Section 2.3.2, “Start a Server Using the Management Console”. When using the Management CLI, the process varies for Standalone Server and Managed Domain instances.
Stop a Standalone Server with the Management CLI
Standalone Servers, started either by a script or manually at a shell prompt, can be shut down from the Management CLI using the shutdown command.

Example 2.5. Stop a Standalone Server instance via the Management CLI

[standalone@localhost:9999 /] shutdown
To restart the JBoss EAP 6 Standalone Server instance, run the instance’s startup script or start it manually as described in Section 2.2.2, “Start JBoss EAP 6 as a Standalone Server”.
Start and Stop a Managed Domain with the Management CLI
The Management Console can selectively start or stop specific servers in a domain. This includes server groups across the whole of a domain as well as specific server instances on a host.

Example 2.6. Stop a Server Host in a Managed Domain via the Management CLI

Similar to Standalone Server instance, the shutdown command is used to shut down a declared Managed Domain host. This example stops a server host named master by declaring the instance name before calling the shutdown operation.
[domain@localhost:9999 /] shutdown --host=master

Example 2.7. Start and Stop a Server Group in a Managed Domain via the Management CLI

This example starts a default server group named main-server-group by declaring the group before calling the start and stop operations.
[domain@localhost:9999 /] /server-group=main-server-group:start-servers
[domain@localhost:9999 /] /server-group=main-server-group:stop-servers

Example 2.8. Start and Stop a Server Instance in a Managed Domain via the Management CLI

This example starts and then stops a server instance named server-one on the master host by declaring the host and server configuration before calling the start and stop operations.
[domain@localhost:9999 /] /host=master/server-config=server-one:start
[domain@localhost:9999 /] /host=master/server-config=server-one:stop

Note

Use the tab key to assist with string completion and to expose visible variables such as available host and server configuration values.

2.3.2. Start a Server Using the Management Console

Procedure 2.11. Start the Server for a Managed Domain

  1. Select the Domain tab at the top of the console and then, select the TOPOLOGY tab. In the left navigation bar, under Domain, select Overview.
  2. From the list of Server Instances, select the server you want to start. Servers that are running are indicated by a check mark.
    Hover the cursor over an instance in this list to show options in blue text below the server's details.
  3. To start the instance, click on the Start Server text when it appears. A confirmation dialogue box will open. Click Confirm to start the server.
Result
The selected server is started and running.

2.3.3. Stop a Server Using the Management Console

Procedure 2.12. Stop a Server in a Managed Domain Using the Management Console

  1. Select the Domain tab at the top of the console and then, select the TOPOLOGY tab. In the left navigation bar, under Domain, select Overview.
  2. A list of available Server Instances is displayed on the Hosts, groups and server instances table. Servers that are running are indicated by a check mark.
  3. Hover the cursor over the chosen server. Click on the Stop Server text that appears. A confirmation dialogue window will appear.
  4. Click Confirm to stop the server.
Result
The selected server is stopped.

2.4. Configuration Files

2.4.1. About JBoss EAP 6 Configuration Files

The configuration for JBoss EAP 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.3. 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. This configuration is used automatically when you start your standalone server.
standalone-full.xml EAP_HOME/standalone/configuration/standalone-full.xml This is an example configuration for a standalone server. It includes support for every possible subsystem except for those required for high availability. To use it, stop your server and restart using the following command: EAP_HOME/bin/standalone.sh -c standalone-full.xml
standalone-ha.xml EAP_HOME/standalone/configuration/standalone-ha.xml This example configuration file enables all of the default subsystems and adds 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 applicable for a managed domain. To use this configuration, stop your server and restart using the following command: EAP_HOME/bin/standalone.sh -c standalone-ha.xml
standalone-full-ha.xml EAP_HOME/standalone/configuration/standalone-full-ha.xml This is an example configuration for a standalone server. It includes support for every possible subsystem, including those required for high availability. To use it, stop your server and restart using the following command: EAP_HOME/bin/standalone.sh -c standalone-full-ha.xml
These are only the default locations. You can specify a different configuration file at runtime.

Note

For information about how to backup JBoss EAP 6 configuration data, refer Section 2.4.2, “Back up JBoss EAP Configuration Data” .

2.4.2. Back up JBoss EAP Configuration Data

Summary
This topic describes the files that must be backed up in order to later restore the JBoss EAP server configuration.

Procedure 2.13. Back Up the Configuration Data

  1. To keep user and profile data, domain, host, slave, and logging configuration, back up the entire contents of the following directories.
    • EAP_HOME/standalone/configuration/
    • EAP_HOME/domain/configuration
  2. Back up any custom modules created in the EAP_HOME/modules/system/layers/base/ directory.
  3. Back up any welcome content in the EAP_HOME/welcome-content/ directory.
  4. Back up any custom scripts created in the EAP_HOME/bin/ directory.

2.4.3. Descriptor-based Property Replacement

Application configuration - for example, datasource connection parameters - typically varies between development, testing, and production deployments. This variance is sometimes accommodated by build system scripts, as the Java EE specification does not contain a method to externalize these configurations. With JBoss EAP 6 you can use descriptor-based property replacement to manage configuration externally.
Descriptor-based property replacement substitutes properties based on descriptors, allowing you to remove assumptions about the environment from the application and the build chain. Environment-specific configurations can be specified in deployment descriptors rather than annotations or build system scripts. You can provide configuration in files or as parameters at the command line.
Descriptor-based property replacement is enabled globally through standalone.xml or domain.xml:

Example 2.9. Descriptor-based property replacement

<subsystem xmlns="urn:jboss:domain:ee:1.2">
  <spec-descriptor-property-replacement>
    true
  </spec-descriptor-property-replacement>
  <jboss-descriptor-property-replacement>
    true
  </jboss-descriptor-property-replacement>
</subsystem>
Java EE descriptor replacement is disabled by default. When enabled, descriptors can be replaced in the following configuration files: ejb-jar.xml and persistence.xml.
JBoss-specific descriptor replacement is enabled by default. When enabled, descriptors can be replaced in the following configuration files:
  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml
For example, given a Bean with the following annotation:

Example 2.10. Example annotation

@ActivationConfigProperty(propertyName = "connectionParameters", propertyValue = "host=192.168.1.1;port=5445")
With descriptor-based property replacement enabled, the connectionParameters can be specified via the command-line as:
./standalone.sh -DconnectionParameters='host=10.10.64.1;port=5445'
To accomplish the same via system properties you use an expression in place of the literal value. Expressions take the format ${parameter:default}. Where an expression is used in configuration, the value of that parameter takes its place. If the parameter does not exist then the specified default value is used instead.

Example 2.11.  Using an Expression in a Descriptor

<activation-config>
  <activation-config-property>
    <activation-config-property-name>
      connectionParameters
      </activation-config-property-name>
    <activation-config-property-value>
      ${jms.connection.parameters:'host=10.10.64.1;port=5445'}
    </activation-config-property-value>
  </activation-config-property>
</activation-config>
The expression ${jms.connection.parameters:'host=10.10.64.1;port=5445'} allows the connection parameters to be overridden by a command-line supplied parameter, while providing a default value.

2.4.4. Enabling or 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 2.14. 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 2.15. 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
  • application.xml
  • web.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.

2.4.5. Nested Expressions

Expressions may be nested, which allows for more advanced use of expressions in place of fixed values. The format of a nested expression is like that of a normal expression, but one expression is embedded in the other, for example:

Example 2.12. Nested expression

${system_value_1${system_value_2}}
Nested expressions are evaluated recursively, so the inner expression is first evaluated, then the outer expression is evaluated. Nested expressions are permitted anywhere that expressions are permitted, with the exception of Management CLI commands.
As for normal expressions, the supported sources for resolving nested expressions are: system properties, environment variables and the Vault. For deployments only, the source can be properties listed in a META-INF/jboss.properties file in the deployment archive. In an EAR or other deployment type that supports subdeployments, the resolution is scoped to all subdeployments if the META-INF/jboss.properties is in the outer deployment (e.g. the EAR) and is scoped to a subdeployment if META-INF/jboss.properties is in the subdeployment archive (e.g. a WAR inside an EAR.)

Example 2.13.  Use a Nested Expression in a Configuration File

A real-life application of a nested expression is in a datasource definition. If the password used in a datasource definition is masked, the resulting line in the datasource definition might be as follows:
<password>${VAULT::ds_ExampleDS::password::1}</password>
Using a nested expression, the value of ds_ExampleDS could be replaced with a system property. If a system property datasource_name is assigned the value ds_ExampleDS, the line in the datasource definition could instead be as follows:
<password>${VAULT::${datasource_name}::password::1}</password>
JBoss EAP would first evaluate the expression ${datasource_name}, then input this to the larger expression and evaluate the resulting expression. The advantage of this configuration is that the name of the datasource is abstracted from the fixed configuration.
Expressions may also be recursive, where an expressions resolves to an expression which is then resolved. Nested expressions and recursive expressions are a form of indirection. Note that recursive expressions are not permitted in Management CLI commands.

Example 2.14.  Recursive Expression

Continuing the previous example, you might use the expression ${foo} which resolves to the expression ${VAULT::ds_ExampleDS::password::1}, which then resolves to a value contained in the Vault: secret.

2.4.6. Configuration File History

The application server configuration files include standalone.xml, 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.4.7. 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.

Example 2.15. Start the server with a saved configuration

  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/standalone/configuration/standalone_xml_history/current/standalone.v1.xml
  2. Start the server with this configuration 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.

Note

The domain configuration history is located in EAP_HOME/domain/configuration/domain_xml_history/current/domain.v1.xml
Start the server with this configuration of the backed up model by passing the relative filename under jboss.domain.config.dir.
To start the domain with this configuration:
EAP_HOME/bin/domain.sh --domain-config=domain_xml_history/current/domain.v1.xml

2.4.8. Save a Configuration Snapshot Using the Management CLI

Summary
Configuration snapshots are a point-in-time copy of the current server configuration. These copies can be saved and loaded by the administrator.
The following example uses the standalone.xml configuration file, but the same process applies to the domain.xml and host.xml configuration files.

Procedure 2.16. Take a Configuration Snapshot and Save It

  • Save a snapshot

    Run the take-snapshot operation to capture a copy of the current server configuration.
    [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 configuration has been saved.

2.4.9. Load a Configuration Snapshot Using the Management CLI

Configuration snapshots are a point-in-time copy of the current server configuration. These copies can be saved and loaded by the administrator. The process of loading snapshots is similar to the method used to Section 2.4.7, “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 file, but the same process applies to the domain.xml and host.xml files.

Procedure 2.17. Load a Configuration Snapshot

  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 configuration snapshot 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 configuration selected in the loaded snapshot.

2.4.10. Delete a Configuration Snapshot Using Management CLI

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

Procedure 2.18. 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.19. 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.4.11. List All Configuration Snapshots Using Management CLI

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

Procedure 2.20. List All Configuration Snapshots

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

2.5. Filesystem Paths

JBoss EAP 6 uses logical names for filesystem paths. The domain.xml, host.xml, and standalone.xml configuration files each include a section for declaring paths.
Other sections of each file can then reference the paths using their logical name, avoiding the need to use absolute paths for each instance and allowing specific host configurations to resolve to universal logical names.
The default logging subsystem configuration, for example, declares jboss.server.log.dir as the logical name for the server’s log directory.

Example 2.16. Relative path example for the logging directory

<file relative-to="jboss.server.log.dir" path="server.log"/>
JBoss EAP 6 automatically provides a number of standard paths without any need for the user to configure them in a configuration file.

Table 2.4. Standard Paths

Value Description
java.ext.dirs The Java development kit extension directory paths.
jboss.home.dir 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.config.dir The directory that contains the server configuration.
jboss.server.log.dir The directory the server will use for log file storage.
jboss.server.temp.dir The directory the server will use for temporary file storage.
jboss.server.deploy.dir The directory that the server will use for storing deployed content.
jboss.controller.temp.dir The directory the host controller will use for temporary file storage.
jboss.domain.base.dir The base directory for domain content.
jboss.domain.config.dir The directory that contains the domain configuration.
jboss.domain.data.dir The directory that the domain will use for persistent data file storage.
jboss.domain.log.dir The directory that the domain will use for persistent log file storage.
jboss.domain.temp.dir The directory that the domain will use for temporary file storage.
jboss.domain.deployment.dir The directory that the domain will use for storing deployed content.
jboss.domain.servers.dir The directory that the domain will use for storing outputs of the managed domain instances.
Override a Path
If you are running a standalone server, you can override all the jboss.server.* paths in one of the two ways.
  • You can pass command line arguments when you start the server. For example:
    bin/standalone.sh -Djboss.server.log.dir=/var/log
  • You can modify the JAVA_OPTS variable in the server configuration file. Open the EAP_HOME/bin/standalone.conf file and add the following line at the end of the file:
    JAVA_OPTS="$JAVA_OPTS -Djboss.server.log.dir=/var/log"
Path overrides is supported for servers running in a managed domain. For example, the jboss.domain.servers.dir can be used to change the base directories of servers in a managed domain.
Add a Custom Path
You can also create your own custom path. For example, you may want to define a relative path to use for logging. You can then change the log handler to use my.relative.path,

Example 2.17. A custom logging path

my.relative.path=/var/log

2.5.1. Directory Grouping

In domain mode, each server's files are stored in the EAP_HOME/domain/ directory. Subdirectories are named according to the directory-grouping attribute, either by server or file type.
Directory Grouping by Server
The default directory grouping is by server. If your administration is server-centric, this configuration is recommended. For example, it allows backups and log file handling to be configured per server instance.

Example 2.18.  Directory Grouping by Server

If JBoss EAP is installed using the Zip method and all default options apply, the directory structure in domain mode will be as follows.
EAP_HOME/domain
             └─ servers
                  ├── server-one
                  │   ├── data
                  │   ├── tmp
                  │   └── log
                  └── server-two
                      ├── data
                      ├── tmp
                      └── log
If the directory-grouping attribute has been changed from the default, and you want to reset it, enter the following management CLI command.
/host=master:write-attribute(name="directory-grouping",value="by-server")
This will update the controller's host.xml configuration file:
<servers directory-grouping="by-server">
  <server name="server-one" group="main-server-group" >
  </server>
  <server name="server-two" group="main-server-group" auto-start="true">
  </server>
</servers>
Directory Grouping by Type
Instead of grouping each servers' directories by server, you can instead group them by file type. If your administration is file type-centric, this configuration is recommended. For example, backup configuration is simpler if you want to include only data files.
To group domain data directories by type, enter the following management CLI command:
/host=master:write-attribute(name="directory-grouping",value="by-type")
This will update the controller's host.xml configuration file:
<servers directory-grouping="by-type">
  <server name="server-one" group="main-server-group" >
  </server>
  <server name="server-two" group="main-server-group" auto-start="true">
  </server>
</servers>

Example 2.19.  Directory Grouping by Type

If JBoss EAP is installed using the Zip method and the domain's files are grouped by type, the directory structure in domain mode will be as follows.
EAP_HOME/domain
            ├── data
            │   └── servers
            │       ├── server-one
            │       └── server-two
            ├── log
            │   └── servers
            │       ├── server-one
            │       └── server-two
            └── tmp
                └── servers
                    ├── server-one
                    └── server-two

2.5.2. Use Case: Overriding Directories

In this example, the objective is to store domain files in the /opt/jboss_eap/data/domain_data directory, and give each top-level directory a custom name. The directory grouping used is the default: by-server.
  • Log files stored in the subdirectory all_logs
  • Data files stored in the subdirectory all_data
  • Temporary files stored in the subdirectory all_temp
  • Servers' files stored in the subdirectory all_servers
To achieve this configuration, you would override several system properties when starting JBoss EAP.
./domain.sh \
      -Djboss.domain.temp.dir=/opt/jboss_eap/data/domain_data/all_temp \
      -Djboss.domain.log.dir=/opt/jboss_eap/data/domain_data/all_logs \
      -Djboss.domain.data.dir=/opt/jboss_eap/data/domain_data/all_data\
      -Djboss.domain.servers.dir=/opt/jboss_eap/data/domain_data/all_servers
The resulting path structure will be as follows:
/opt/jboss_eap/data/domain_data/
├── all_data
│   └── content
├── all_logs
│   ├── host-controller.log
│   └── process-controller.log
├── all_servers
│   ├── server-one
│   │   ├── data
│   │   │   ├── content
│   │   │   ├── logging.properties
│   │   ├── log
│   │   │   └── server.log
│   │   └── tmp
│   │       ├── vfs
│   │       │   └── temp
│   │       └── work
│   │           └── jboss.web
│   │               └── default-host
│   └── server-two
│       ├── data
│       │   ├── content
│       │   ├── logging.properties
│       ├── log
│       │   └── server.log
│       └── tmp
│           ├── vfs
│           │   └── temp
│           └── work
│               └── jboss.web
│                   └── default-host
└── all_temp
    └── auth
          ...

Chapter 3. Management Interfaces

3.1. Manage the Application Server
3.2. Management Application Programming Interfaces (APIs)
3.3. The Management Console
3.3.1. Management Console
3.3.2. Log in to the Management Console
3.3.3. Change the Language of the Management Console
3.3.4. Analytics in JBoss EAP Console
3.3.5. Enable Google Analytics in JBoss EAP Console
3.3.6. Disable Google Analytics in JBoss EAP Console
3.3.7. Configure a Server Using the Management Console
3.3.8. Add a Deployment in the Management Console
3.3.9. Create a New Server in the Management Console
3.3.10. Change the Default Log Levels Using the Management Console
3.3.11. Create a New Server Group in the Management Console
3.3.12. Viewing Logs in the Management Console
3.3.13. Customer Portal Integration in the Management Console
3.4. The Management CLI
3.4.1. About the Management Command Line Interface (CLI)
3.4.2. Launch the Management CLI
3.4.3. Quit the Management CLI
3.4.4. Connect to a Managed Server Instance Using the Management CLI
3.4.5. Obtain Help with the Management CLI
3.4.6. Use the Management CLI in Batch Mode
3.4.7. CLI Batch Mode Commands
3.4.8. Use Operations and Commands in the Management CLI
3.4.9. Use if-else Control Flow with the Management CLI
3.4.10. Management CLI Configuration Options
3.4.11. Reference of Management CLI Commands
3.4.12. Reference of Management CLI Operations
3.4.13. Property Substitution in the Management CLI
3.5. Management CLI Operations
3.5.1. Display the Attributes of a Resource with the Management CLI
3.5.2. Display the Active User in the Management CLI
3.5.3. Display System and Server Information in the Management CLI
3.5.4. Display an Operation Description using the Management CLI
3.5.5. Display the Operation Names using the Management CLI
3.5.6. Display Available Resources using the Management CLI
3.5.7. Display Available Resource Descriptions using the Management CLI
3.5.8. Reload the Application Server using the Management CLI
3.5.9. Shut the Application Server down using the Management CLI
3.5.10. Configure an Attribute with the Management CLI
3.5.11. Configure System Properties Using the Management CLI
3.5.12. Create a New Server with the Management CLI
3.6. The Management CLI Command History
3.6.1. About the Management CLI Command History
3.6.2. View Management CLI Command History
3.6.3. Clear the Management CLI Command History
3.6.4. Disable the Management CLI Command History
3.6.5. Enable the Management CLI Command History
3.7. Management Interface Audit Logging
3.7.1. About Management Interface Audit Logging
3.7.2. Enable Management Interface Audit Logging to a File
3.7.3. Enable Management Interface Audit Logging to a Syslog Server
3.7.4. Disable Management Interface Audit Logging
3.7.5. Read a Management Interface Audit Log

3.1. Manage the Application Server

JBoss EAP 6 uses XML files for server configuration and offers three approaches to configuring and managing JBoss EAP 6 servers; a web interface, a command line client and direct editing of the XML configuration files.
The recommended methods for editing the configuration files are the Management CLI and the new, web-based Management Console. Edits made to the XML configuration files is still possible but configuration and administration through the Management Console and Management CLI provides extra validation and advanced features for server instance management.
Edits made to a server configuration by any of the three approaches are synchronized across the different views.

Note

However, edits made to the XML configuration files while a server instance is running will be overwritten by the server model. All comments added to an XML configuration file while a server instance is running will be removed as well.
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.
As well as being the recommended management tools, the Management Console and Management CLI also serve as examples of the underlying Management API that enables expert users to develop their own tools if they desire.

3.2. Management Application Programming Interfaces (APIs)

HTTP API
The Management Console is a web interface built with the Google Web Toolkit (GWT). It communicates with the server using the HTTP management interface.
The HTTP API endpoint is the entry point for management clients which rely on the HTTP protocol to integrate with the management layer.
Management clients that rely on the HTTP protocol use 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 Management Console but offers integration capabilities for other clients as well.
The HTTP API endpoint is co-located with the domain controller or the standalone server instance. It serves two different contexts: one for executing management operations and the other to access the web interface. By default, the HTTP API endpoint runs on port 9990.

Example 3.1. HTTP API Configuration File Example

<management-interfaces>
  [...]
  <http-interface security-realm="ManagementRealm">
     <socket-binding http="management-http"/>
  </http-interface>
</management-interfaces>
The Management Console is served on the same port as the HTTP management API. It is important to distinguish between the Management Console as accessed on a default localhost, the Management Console as accessed remotely by a specific host and port combination, and the exposed domain API.

Table 3.1. URLs to access the Management Console or exposed HTTP API

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.

Example 3.2. Retrieve attribute values using the HTTP API

The following URL retrieves the HTTP web connector attribute values (the default operation is read-resource).
http://hostname:9990/management/subsystem/web/connector/http

Example 3.3. Retrieve a single attribute value using the HTTP API

The following URL retrieves the enabled attribute for the ExampleDS datasource.
http://hostname:9990/management/subsystem/datasources/data-source/ExampleDS?operation=attribute&name=enabled
See Section 10.4.1, “Deploy an application using the HTTP API” for instructions on deploying applications using the HTTP API.
Native API
The Management CLI is a Native API tool. It is available for a Managed Domain or Standalone server instance, allowing an administrator to connect to a domain controller or 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 is 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. It runs on port 9999 by default.

Example 3.4. Native API Configuration File Example

<management-interfaces>
  <native-interface security-realm="ManagementRealm">
    <socket-binding native="management-native"/>
  </native-interface>
  [...]
</management-interfaces>

3.3. The Management Console

3.3.1. Management Console

The Management Console is a web-based administration tool for JBoss EAP 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.3.2. Log in to the Management Console

Prerequisites

  • JBoss EAP 6 must be running.
  • You must have already created a user with permissions to access the Console.
  1. Launch your web browser and go to this address: http://localhost:9990/console/App.html

    Note

    Port 9990 is predefined as the Management Console socket binding.
  2. Enter your username and password to log in to the Management Console.
    The login screen for the Management console.

    Figure 3.1. Log in screen for the Management Console

Result
Once logged in, you are redirected to the following address and the Management Console landing page appears: http://localhost:9990/console/App.html#home

3.3.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.1. Change the Language of the Web-based Management Console

  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. The system refreshes your web browser automatically to use the new locale.

3.3.4. Analytics in JBoss EAP Console

About Google Analytics
Google Analytics is a free web analytics service which provides comprehensive usage statistics on a website. It provides vital data regarding a site's visitors, including their visits, page views, pages per visit and average time spent on site. Google Analytics provides more visibility around a website's presence and its visitors.
About Google Analytics in JBoss EAP Management Console
JBoss EAP 6 provides users the option to enable or disable Google Analytics in the management console. The Google Analytics feature aims to help Red Hat EAP team understand how the customers are using the console and which parts of the console matter the most to the customers. This information will in-turn help the team adapt the console design, features and content to the immediate needs of the customers.

Note

By default, Google Analytics is disabled in JBoss EAP 6 console and its usage is optional.

3.3.5. Enable Google Analytics in JBoss EAP Console

To enable Google Analytics in JBoss EAP Management Console:
  • Log in to the Management Console
  • Click Settings on the Management Console
    Description

    Figure 3.2. Log in screen of the Management Console

  • Select Enable Usage Data Collection checkbox on the Settings dialog and click Save button. Confirm the application reload to activate the new settings.
    Description

    Figure 3.3. Settings dialog (Enable Usage Data Collection)

3.3.6. Disable Google Analytics in JBoss EAP Console

To disable Google Analytics in JBoss EAP Management Console:
  • Log in to the Management Console
  • Click Settings on the Management Console
    Description

    Figure 3.4. Log in screen of the Management Console

  • Uncheck the Enable Usage Data Collection option on the Settings dialog to remove the selection. Click Save button. Confirm the application reload to activate the new settings.
    Description

    Figure 3.5. Settings dialog (Disable Usage Data Collection)

3.3.7. Configure a Server Using the Management Console

Procedure 3.2. Configure the Server

  1. Select the Domain tab from the top of the console. Available server instances will be displayed in a table.
  2. Click Server Configurations.
    The Server Configurations panel for the relevant host appears.
  3. Select the server instance from the Available Server Configurations table.
  4. Click Edit above the details of the chosen server.
  5. Make changes to the configuration attributes.
  6. Click Save to finish.
Server configuration

Figure 3.6. Server configuration

Result
The server configuration is changed, and will take effect next time the server restarts.

3.3.8. Add a Deployment in the Management Console

  1. Select the Deployments tab at the top of the console.
  2. Select Add on the Content Repository tab. A Create Deployment dialog box appears.
    The Manage Deployments panel for a standalone server.

    Figure 3.7. Manage standalone deployments

  3. In the dialog box, click Browse. Browse to the file you want to deploy, select it and upload it. Click Next to proceed.
    The Upload dialog box requesting a file for deployment.

    Figure 3.8. Deployment selection

  4. Verify the deployment name and runtime name that appear in the Create Deployments dialog box. Click Save to upload the file once the names are verified.
Result
The selected content is uploaded to the server and is now ready for deployment.

3.3.9. Create a New Server in the Management Console

Procedure 3.3. Create a New Server Configuration

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

    Select the Domain tab from the top of the console.
    Server Configuration

    Figure 3.9. Server Configuration

  2. Click Server Configurations in the left menu.
  3. Create a new configuration

    1. Select the Add button above the Available Server Configurations table.
    2. Enter the basic server settings in the Create Server Configuration dialog.
    3. Select the Save button to save the new Server Configuration.
    Create a new configuration

    Figure 3.10. Create a new configuration

3.3.10. Change the Default Log Levels Using the Management Console

Procedure 3.4. Edit the Logging Levels

  1. Navigate to the Logging panel in the Management Console

    1. If you are working with a managed domain, select the Configuration tab at the top 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, expand the Core menu from the list on the left of the console and click the Logging entry.
    3. Click on the Log Categories tab in the top of the console.
    Logging panel

    Figure 3.11. 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 click Edit in the Details section below.
    2. Set the log level for the category with the Log Level drop-down box. Click the Save button when done.
Result
The log levels for the relevant categories are now updated.

3.3.11. Create a New Server Group in the Management Console

Procedure 3.5. Configure and Add a new Server Group

  1. Navigate to the Server Groups view

    Select the Domain tab from the top of the console.
  2. Select Server Groups in the left hand column.
    The Server Groups view for a managed domain.

    Figure 3.12. 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 for the server group.
    3. Select the socket binding for the server group.
    4. Click the Save button to save your new group.
    The Create Server Group dialog. A server with the name new-server-group will be created, based on the main-server-group template.

    Figure 3.13. The Create Server Group dialog

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

3.3.12. Viewing Logs in the Management Console

You can view server and application logs in the JBoss EAP 6 Management Console in order to help diagnose errors, performance problems, and other issues. For a log to be viewable in the Management Console Log Viewer, it must be located in the server's jboss.server.log.dir directory. The JBoss EAP 6 Log Viewer also respects user RBAC role assignments, so a user logged in to the Management Console can only view logs that they are authorized to access.

Procedure 3.6. View JBoss EAP 6 Logs in the Management Console

  1. Select the Runtime tab from the top of the Management Console.
    1. If you are using a Managed Domain, use the Change Server button on the left menu to select the JBoss EAP 6 server that you want to view the logs of.
  2. Expand the Platform menu on the left, and select Log Viewer.
  3. Select a log file from the list, and click the View button.
    You can also click Download to download the log file to your local machine.

    Note

    The Management Console Log Viewer displays a confirmation if you attempt to open a log file that is larger than 15MB.
    The Management Console Log Viewer is not intended to be a text editor replacement for viewing very large log files (>100MB). Opening very large log files in the Management Console Log Viewer could crash your web browser, so you should always download large log files separately and open them in a text editor.
  4. The selected log will open as a new tab within the Management Console. You can open multiple log files in other tabs by returning to the LOG FILES tab and repeating the previous step.

3.3.13. Customer Portal Integration in the Management Console

You can use the access.redhat.com interface to browse sections of the Red Hat Customer Portal without leaving the Management Console of your JBoss EAP installation.
The top navigation bar of the Management Console contains a drop-down menu: Red Hat Access. Clicking on this menu will reveal three task-specific links to the Customer Portal:
  • Search Customer Portal
  • Open Case
  • Modify Case
The features of each of these links are discussed in more detail below.

Note

If you are not already logged in to the Customer Portal when you click one of these links, a dialogue box will appear, prompting you to log in. You must be logged into the Customer Portal in the browser session that you are using to access the Management Console. If you are logged in to the Customer Portal in one browser but use a different browser to access the Management Console, you will be prompted to log in.

Search Customer Portal

Clicking on Search Customer Portal presents a page containing a search box. You can enter search terms or phrases to find Knowledge Base articles.
Once you have performed a search, you can select an item from the list of results and see the entire article displayed in a separate pane.

Open Case

The Open Case page allows you to open a new support case.
You will be presented with a form to complete in order to open a new support case. A list of recommended Knowledge Base articles is provided beside the form. This list refreshes based on the details provided for the support case.

Modify Case

The Modify Case page allows you to view and modify existing support cases.
You can refine the results by limiting your search to grouped or ungrouped cases, and by the state of the case (open, closed, or either).
After selecting a specific support case, you can view or update the details of the support case, as well as add comments.

3.4. The Management CLI

3.4.1. About the Management Command Line Interface (CLI)

The Management Command Line Interface (CLI) is a command line administration tool for JBoss EAP 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 mode, allowing multiple tasks to be run as a group.

3.4.2. Launch the Management CLI

Procedure 3.7. Launch CLI in Linux or Microsoft Windows Server

    • 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 Microsoft Windows Server

      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.4.3. Quit the Management CLI

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

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

Procedure 3.8. Connect to a Managed Server Instance

  • 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.4.5. Obtain Help with the Management CLI

Summary
Sometimes you might need guidance if you need to learn a CLI command or feel unsure about what to do. The Management CLI features a help dialog with general and context-sensitive options. (Note that 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.)
  1. For general help

    From the Management CLI, enter the help command:
    [standalone@localhost:9999 /] help
  2. Obtain 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, enter the command, followed by --help.
    [standalone@localhost:9999 /] deploy --help
Result
The CLI help information is displayed.

3.4.6. Use the Management CLI in Batch Mode

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

Note

Batch mode does not support conditional statements.

Procedure 3.9. Batch Mode Commands and Operations

  1. Enter batch mode

    Enter batch mode with the batch command.
    [standalone@localhost:9999 /] batch
    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.4.8, “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.
    Refer to Section 3.4.7, “CLI Batch Mode Commands” for a full list of commands available for working with batches.
  4. Batch commands stored in external files

    Frequently run batch commands can be stored in an external text file and can either be loaded by passing the full path to the file as an argument to the batch command or executed directly by being an argument to the run-batch command.
    You can create a batch command file using a text editor. Each command must be on a line by itself and the CLI should be able to access it.
    The following command will load a myscript.txt file in the batch mode. All commands in this file will now be accessible to be edited or removed. New commands can be inserted. Changes made in this batch session do not persist to the myscript.txt file.
    [standalone@localhost:9999 /] batch --file=myscript.txt
    The following will instantly run the batch commands stored in the file myscript.txt
    [standalone@localhost:9999 /] run-batch --file=myscript.txt
Result
The entered sequence of operation requests is completed as a batch.

3.4.7. CLI Batch Mode Commands

This table provides a list of valid batch commands that can be used in the JBoss EAP 6 CLI. These commands can only be used to work with batches.

Table 3.2. CLI Batch Mode Commands

Command Name Description
list-batch List of the commands and operations in the current batch.
edit-batch-line line-number edited-command Edit a line in the current batch by providing the line number to edit and the edited command. Example: edit-batch-line 2 data-source disable --name=ExampleDS.
move-batch-line fromline toline Re-order the lines in the batch by specifying the line number you want to move as the first argument and its new position as the second argument. Example: move-batch-line 3 1.
remove-batch-line linenumber Remove the batch command at the specified line. Example: remove-batch-line 3.
holdback-batch [batchname]
You can postpone or store a current batch by using this command. Use this if you want to suddenly execute something in the CLI outside the batch. To return to this heldback batch, simply type batch again at the CLI command line.
If you provide a batchname while using holdback-batch command the batch will be stored under that name. To return to the named batch, use the command batch batchname. Calling the batch command without a batchname will start a new (unnamed) batch. There can be only one unnamed heldback batch.
To see a list of all heldback batches, use the batch -l command.
discard-batch Dicards the currently active batch.

3.4.8. Use Operations and Commands in the Management CLI

Procedure 3.10. Create, Configure and Execute Requests

  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.

      Note

      Running the CLI commands in Domain Mode requires host and server specification. For example, /host=master/server=server-one/subsystem=logging

      Example 3.5. 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.6. 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-operation-description command on a resource node, passing the operation name as a parameter. Refer to Example 3.7, “Determine operation parameters” for details.

      Example 3.7. 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" => true
          }
      }
  2. Enter the full operation request

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

    Example 3.8. 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.4.9. Use if-else Control Flow with the Management CLI

The Management CLI supports if-else control flow, which allows you to choose which set of commands and operations to execute based on a condition. The if condition is a boolean expression which evaluates the response of the management command or operation specified after the of keyword.
Expressions can contain any of the following items:
  • Conditional operators (&&, ||)
  • Comparison operators (>, >=, <, <=, ==, !=)
  • Parentheses to group and prioritize expressions

Example 3.9. Using an if statement with Management CLI commands

This example attempts to read the system property test. If outcome is not success (meaning that the property does not exist), then the system property will be added and set to true.
if (outcome != success) of /system-property=test:read-resource
    /system-property=test:add(value=true)
end-if
The condition above uses outcome, which is returned when the CLI command after the of keyword is executed, as shown below:
[standalone@localhost:9999 /] /system-property=test:read-resource
{
    "outcome" => "failed",
    "failure-description" => "JBAS014807: Management resource '[(\"system-property\" => \"test\")]' not found",
    "rolled-back" => true
}

Example 3.10. Using an if-else statement with Management CLI commands

This example checks the launch type of the server process (STANDALONE or DOMAIN) and issues the appropriate CLI command to enable the ExampleDS datasource.
if (result == STANDALONE) of /:read-attribute(name=launch-type)
    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled, value=true)
else
    /profile=full/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled, value=true)
end-if
Management CLI commands with if-else control flow can be specified in a file (one per line) and passed to the jboss-cli.sh script to be executed non-interactively.
EAP_HOME/bin/jboss-cli.sh --connect --file=CLI_FILE

Note

The use of nested if-else statements is not supported.

3.4.10. Management CLI Configuration Options

The Management CLI configuration file - jboss-cli.xml - is loaded each time the CLI is started. It must be located either in the directory $EAP_HOME/bin or a directory specified in the system property jboss.cli.config.
default-controller
Configuration of the controller to which to connect if the connect command is executed without any parameters.

default-controller Parameters

host
Hostname of the controller. Default: localhost.
port
Port number on which to connect to the controller. Default: 9999.
validate-operation-requests
Indicates whether the parameter list of the operation requests is to be validated before the requests are sent to the controller for execution. Type: Boolean. Default: true.
history
This element contains the configuration for the commands and operations history log.

history Parameters

enabled
Indicates whether or not the history is enabled. Type: Boolean. Default: true.
file-name
Name of the file in which the history is to be stored. Default = .jboss-cli-history.
file-dir
Directory in which the history is to be stored. Default = $USER_HOME
max-size
Maximum size of the history file. Default: 500.
resolve-parameter-values
Whether to resolve system properties specified as command argument (or operation parameter) values before sending the operation request to the controller or let the resolution happen on the server side. Type: Boolean. Default = false.
connection-timeout
The time allowed to establish a connection with the controller. Type: Integer. Default: 5000 seconds.
ssl
This element contains the configuration for the Key and Trust stores used for SSL.

Warning

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2 in all affected packages.

ssl Parameters

vault
Type: vaultType
key-store
Type: string.
key-store-password
Type: string.
alias
Type: string
key-password
Type: string
trust-store
Type: string.
trust-store-password
Type: string.
modify-trust-store
If set to true, the CLI will prompt the user when unrecognised certificates are received and allow them to be stored in the truststore. Type: Boolean. Default: true.

vaultType

If neither code nor module are specified, the default implementation will be used. If code is specified but not module, it will look for the specified class in the Picketbox module. If module and code are specified, it will look for the class specified by codein the module specified by 'module'.
code
Type: String.
module
Type: String
silent
Specifies if informational and error messages are to be output to the terminal. Even if the false is specified, the messages will still be logged using the logger if its configuration allows and/or if the output target was specified as part of the command line using >. Default: False.

3.4.11. Reference of Management CLI Commands

Summary
The topic Section 3.4.5, “Obtain 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.3. 

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, when invoked without 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.
echo
Available from JBoss EAP 6.4, the echo command outputs to the console the specified text. The text is output verbatim so the use of variables is not available.
Example:
echo Phase one complete
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.4.12. 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.5.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.5.4, “Display an Operation Description using the Management CLI”.

Table 3.4. 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.13. Property Substitution in the Management CLI

JBoss EAP 6 supports the use of preset element and property expressions in the Management Commmand Line Interface. These expressions will be resolved to their defined values during the execution of the command.
The following properties can be substituted with expressions:
  • the operation address part of the operation request (as node types and/or names);
  • operation name;
  • operation parameter names;
  • header names and values;
  • command names;
  • command argument names.
By default, the CLI performs property substitution for every line except for argument or parameter values. Argument and parameter values are resolved in the server at runtime. If you require property substitution for argument or parameter values to occur in the Management CLI client and have it send the resolved values to the server, complete the following procedure.

Procedure 3.11. Enable Property Substitution in the Management CLI

  1. Open the file EAP_HOME/bin/jboss-cli.xml.
  2. Locate the resolve-parameter-values parameter and change the value to true (the default is false).
    <!-- whether to resolve system properties specified as command argument or operation parameter values in the Management CLI VM before sending the operation requests to the controller -->
        <resolve-parameter-values>true</resolve-parameter-values>
    
This element only affects operation request parameter values and command argument values. It does not impact the rest of the command line. This means system properties present on the command line will be resolved during the parsing of the line regardless of what the value of resolve-parameter-values element is, unless it is a parameter/argument value.
Refer to Section 3.4.10, “Management CLI Configuration Options” for other Management CLI configuration options.
Be aware that system values used in Management CLI commands must have already been defined. You must include the --properties=/path/to/file.properties argument or one or more -Dkey=VALUE parameters, when starting your Management CLI instance. The properties file uses a standard key=value syntax.
Property keys are denoted in your Management CLI commands using the syntax ${MY_VAR}.

Example 3.11. Example: Using properties in Management CLI commands

/subsystem=datasources/data-source=${datasourcename}:add(connection-url=jdbc:oracle:thin:@server:1521:ora1, jndi-name=java:/jboss/${name}, driver-name=${drivername})

3.5. Management CLI Operations

3.5.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.12. Display the Current Runtime Value of a Selected Attribute

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.12. 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.5.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.13. Display the Active User in the Management CLI Using the whoami Operation

  • 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.13. 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.5.3. Display System and Server Information in the Management CLI

Procedure 3.14. Display System and Server Information in the Management CLI

  • 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.5.4. Display an Operation Description using the Management CLI

Procedure 3.15. Execute the Command in Management CLI

  • 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.4.8, “Use Operations and Commands in the Management CLI”.
    [standalone@localhost:9999 /]:read-operation-description(name=name-of-operation)

Example 3.14. 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",
        "request-properties" => {},
        "reply-properties" => {
            "type" => OBJECT,
            "value-type" => {
                "directory" => {
                    "type" => STRING,
                    "description" => "The directory where the snapshots are stored",
                    "expressions-allowed" => false,
                    "required" => true,
                    "nillable" => false,
                    "min-length" => 1L,
                    "max-length" => 2147483647L
                },
                "names" => {
                    "type" => LIST,
                    "description" => "The names of the snapshots within the snapshots directory",
                    "expressions-allowed" => false,
                    "required" => true,
                    "nillable" => false,
                    "value-type" => STRING
                }
            }
        },
        "access-constraints" => {"sensitive" => {"snapshots" => {"type" => "core"}}},
        "read-only" => false
    }
}
Result
The description is displayed for the chosen operation.

3.5.5. Display the Operation Names using the Management CLI

Procedure 3.16. Execute the Command in Management CLI

Example 3.15. 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",
        "resolve-expression",
        "resolve-internet-address",
        "server-set-restart-required",
        "shutdown",
        "take-snapshot",
        "undefine-attribute",
        "upload-deployment-bytes",
        "upload-deployment-stream",
        "upload-deployment-url",
        "validate-address",
        "validate-operation",
        "whoami",
        "write-attribute"
    ]
}
Result
The available operation names are displayed.

3.5.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.
Execute the Command in Management CLI
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.16. Using the read-resource operation at the root level

[standalone@localhost:9999 /]:read-resource
{
    "outcome" => "success",
    "result" => {
        "management-major-version" => 1,
        "management-micro-version" => 0,
        "management-minor-version" => 7,
        "name" => "localhost",
        "namespaces" => [],
        "product-name" => "EAP",
        "product-version" => "6.4.0.GA",
        "profile-name" => undefined,
        "release-codename" => "Janus",
        "release-version" => "7.5.0.Final-redhat-17",
        "schema-locations" => [],
        "core-service" => {
            "service-container" => undefined,
            "server-environment" => undefined,
            "module-loading" => undefined,
            "platform-mbean" => undefined,
            "management" => undefined,
            "patching" => undefined
        },
        "deployment" => undefined,
        "deployment-overlay" => undefined,
        "extension" => {
            "org.jboss.as.clustering.infinispan" => 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.jsf" => undefined,
            "org.jboss.as.logging" => undefined,
            "org.jboss.as.mail" => undefined,
            "org.jboss.as.naming" => 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" => {
            "jaxrs" => undefined,
            "jsf" => undefined,
            "jca" => undefined,
            "jmx" => undefined,
            "threads" => undefined,
            "webservices" => undefined,
            "sar" => undefined,
            "remoting" => undefined,
            "infinispan" => undefined,
            "weld" => undefined,
            "ejb3" => undefined,
            "transactions" => undefined,
            "datasources" => undefined,
            "deployment-scanner" => undefined,
            "logging" => undefined,
            "jdr" => undefined,
            "pojo" => undefined,
            "jpa" => undefined,
            "naming" => undefined,
            "ee" => undefined,
            "mail" => undefined,
            "web" => undefined,
            "resource-adapters" => undefined,
            "security" => undefined
        },
        "system-property" => undefined
    }
}
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.17. Expose child node resources from the root node

[standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource                      
{
    "outcome" => "success",
    "result" => {
        "configuration" => undefined,
        "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" => 443,
        "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.18. 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" => {
        "configuration" => undefined,
        "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" => 443,
        "scheme" => "http",
        "secure" => false,
        "socket-binding" => "http",
        "ssl" => undefined,
        "virtual-server" => undefined
    }
}
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 bytes received by the HTTP connector.

Example 3.19. 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" => {
        "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
    }
}

3.5.7. Display Available Resource Descriptions using the Management CLI

Execute the Command in Management CLI
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.4.8, “Use Operations and Commands in the Management CLI”.
[standalone@localhost:9999 /]:read-resource-description
Use optional parameters
The read-resource-description operation allows the use of the additional parameters.

  • Use the operations parameter to include descriptions of the resource's operations.
    [standalone@localhost:9999 /]:read-resource-description(operations=true)
  • 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)
  • Use the recursive parameter to include recursive descriptions of the child resources.
    [standalone@localhost:9999 /]:read-resource-description(recursive=true)
  • 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)
  • Use the access-control parameter to get the information about the permissions the current caller has for this resource.
    [standalone@localhost:9999 /]:read-resource-description(access-control=none)
Result
Descriptions of the available resources are displayed.

3.5.8. Reload the Application Server using the Management CLI

From the Management CLI, use the reload operation to shut down all services and restart the JBoss EAP instance. Note that the JVM itself is not restarted. When the reload is complete the Management CLI will automatically reconnect.

Example 3.20. Reload the Application Server

[standalone@localhost:9999 /]reload
{"outcome" => "success"}

3.5.9. Shut the Application Server down using the Management CLI

Procedure 3.17. Shut down the Application Server

  • Run the shutdown operation

    • From the Management CLI, use the shutdown operation to shut the server down via the System.exit(0) system call. For more details on operation requests, refer to the topic Section 3.4.8, “Use Operations and Commands in the Management CLI”.
      • In the standalone mode, use the following command:
        [standalone@localhost:9999 /]shutdown
      • In the domain mode, use the following command with the appropriate host name:
        [domain@localhost:9999 /]shutdown --host=master
    • To connect to a detached CLI instance and shut down the server, execute the following command:
      jboss-cli.sh --connect command=shutdown
      
    • To connect to a remote CLI instance and shut down the server, execute the following command:
      [disconnected /] connect IP_ADDRESS
      [standalone@IP_ADDRESS:9999 /] shutdown
      
      Replace IP_ADDRESS with the IP address of your instance.

Note

Appending the --restart=true argument to the shutdown command (as shown below) will prompt the server to restart.
[standalone@localhost:9999 /]shutdown --restart=true
Result
The application server is shut down. The Management CLI will be disconnected as the runtime is unavailable.

3.5.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.18. Configure a Resource Attribute with the Management CLI

  • 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.21. 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.11. Configure System Properties Using the Management CLI

Procedure 3.19. Configure System Properties Using the Management CLI

  1. Start the JBoss EAP server.
  2. Launch the Management CLI using the command for your operating system.
    For Linux:
    EAP_HOME/bin/jboss-cli.sh --connect
    For Windows:
    EAP_HOME\bin\jboss-cli.bat --connect
  3. Add a system property.
    The command you use depends on whether you are running a standalone server or a managed domain. If you are running a managed domain, you can add system properties to any or all of the servers running in that domain.
    • Add a system property on a standalone server using the following syntax:
      /system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

      Example 3.22. Add a system property to a standalone server

      [standalone@localhost:9999 /] /system-property=property.mybean.queue:add(value=java:/queue/MyBeanQueue)
      {"outcome" => "success"} 
    • Add a system property to all hosts and servers in a managed domain using the following syntax:
      /system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

      Example 3.23. Add a system property to all servers in a managed domain

      [domain@localhost:9999 /] /system-property=property.mybean.queue:add(value=java:/queue/MyBeanQueue)
      {
          "outcome" => "success",
          "result" => undefined,
          "server-groups" => {"main-server-group" => {"host" => {"master" => {
              "server-one" => {"response" => {"outcome" => "success"}},
              "server-two" => {"response" => {"outcome" => "success"}}
          }}}}
      } 
    • Add a system property to a host and its server instances in a managed domain using the following syntax:
      /host=master/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

      Example 3.24. Add a system property to a host and its servers in a domain

      [domain@localhost:9999 /] /host=master/system-property=property.mybean.queue:add(value=java:/queue/MyBeanQueue)
      {
          "outcome" => "success",
          "result" => undefined,
          "server-groups" => {"main-server-group" => {"host" => {"master" => {
              "server-one" => {"response" => {"outcome" => "success"}},
              "server-two" => {"response" => {"outcome" => "success"}}
          }}}}
      } 
    • Add a system property to a server instance in a managed domain using the following syntax:
      /host=master/server-config=server-one/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)

      Example 3.25. Add a system property to a server instance in a managed domain

      [domain@localhost:9999 /] /host=master/server-config=server-one/system-property=property.mybean.queue:add(value=java:/queue/MyBeanQueue)
      {
          "outcome" => "success",
          "result" => undefined,
          "server-groups" => {"main-server-group" => {"host" => {"master" => {"server-one" => {"response" => {"outcome" => "success"}}}}}}
      }
       
  4. Read a system property.
    The command you use depends on whether you are running a standalone server or a managed domain.
    • Read a system property from a standalone server using the following syntax:
      /system-property=PROPERTY_NAME:read-resource

      Example 3.26. Read a system property from a standalone server

      [standalone@localhost:9999 /] /system-property=property.mybean.queue:read-resource
      {
          "outcome" => "success",
          "result" => {"value" => "java:/queue/MyBeanQueue"}
      }
       
    • Read a system property from all hosts and servers in a managed domain using the following syntax:
      /system-property=PROPERTY_NAME:read-resource

      Example 3.27. Read a system property from all servers in a managed domain

      [domain@localhost:9999 /] /system-property=property.mybean.queue:read-resource
      {
          "outcome" => "success",
          "result" => {
              "boot-time" => true,
              "value" => "java:/queue/MyBeanQueue"
          }
      } 
    • Read a system property from a host and its server instances in a managed domain using the following syntax:
      /host=master/system-property=PROPERTY_NAME:read-resource

      Example 3.28. Read a system property from a host and its servers in a domain

      [domain@localhost:9999 /] /host=master/system-property=property.mybean.queue:read-resource
      {
          "outcome" => "success",
          "result" => {
              "boot-time" => true,
              "value" => "java:/queue/MyBeanQueue"
          }
      }
       
    • Read a system property from a server instance in a managed domain using the following syntax:
      /host=master/server-config=server-one/system-property=PROPERTY_NAME:read-resource

      Example 3.29. Read a system property from a server instance in a managed domain

      [domain@localhost:9999 /] /host=master/server-config=server-one/system-property=property.mybean.queue:read-resource
      {
          "outcome" => "success",
          "result" => {
              "boot-time" => true,
              "value" => "java:/queue/MyBeanQueue"
          }
      } 
  5. Remove a system property.
    The command you use depends on whether you are running a standalone server or a managed domain.
    • Remove a system property from a standalone server using the following syntax:
      /system-property=PROPERTY_NAME:remove

      Example 3.30. Remove a system property from a standalone server

      [standalone@localhost:9999 /] /system-property=property.mybean.queue:remove
      {"outcome" => "success"} 
    • Remove a system property from all hosts and servers in a managed domain using the following syntax:
      /system-property=PROPERTY_NAME:remove

      Example 3.31. Remove a system property from all hosts and servers in a domain

      [domain@localhost:9999 /] /system-property=property.mybean.queue:remove
      {
          "outcome" => "success",
          "result" => undefined,
          "server-groups" => {"main-server-group" => {"host" => {"master" => {
              "server-one" => {"response" => {"outcome" => "success"}},
              "server-two" => {"response" => {"outcome" => "success"}}
          }}}}
      }
       
    • Remove a system property from a host and its server instances in a managed domain using the following syntax:
      /host=master/system-property=PROPERTY_NAME:remove

      Example 3.32. Remove a system property from a host and its instances in a domain

      [domain@localhost:9999 /] /host=master/system-property=property.mybean.queue:remove
      {
          "outcome" => "success",
          "result" => undefined,
          "server-groups" => {"main-server-group" => {"host" => {"master" => {
              "server-one" => {"response" => {"outcome" => "success"}},
              "server-two" => {"response" => {"outcome" => "success"}}
          }}}}
      }
       
    • Remove a system property from a server instance in a managed domain using the following syntax:
      /host=master/server-config=server-one/system-property=PROPERTY_NAME:remove

      Example 3.33. Remove a system property from a server in a managed domain

      [domain@localhost:9999 /] /host=master/server-config=server-one/system-property=property.mybean.queue:remove
      {
          "outcome" => "success",
          "result" => undefined,
          "server-groups" => {"main-server-group" => {"host" => {"master" => {"server-one" => {"response" => {"outcome" => "success"}}}}}}
      }
       

Note

Any system property which contains the text password (regardless of case) is replaced with the text redacted when output via logging. This improves security by avoiding having passwords output in plain text in log files.

3.5.12. Create a New Server with the Management CLI

The following example creates a new server on the host master and adds it to clustered-server-group:
[domain@localhost:9999 /] /host=master/server-config=clustered-server-1:add(group=clustered-server-group)

3.6. The Management CLI Command History

3.6.1. About 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.6.2. View Management CLI Command History

Procedure 3.20. View the Management CLI Command History

  • 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.6.3. Clear the Management CLI Command History

Procedure 3.21. Clear the Management CLI Command History

  • 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.6.4. Disable the Management CLI Command History

Procedure 3.22. Disable the Management CLI Command History

  • 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.6.5. Enable the Management CLI Command History

Procedure 3.23. Enable the Management CLI Command History

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

3.7. Management Interface Audit Logging

3.7.1. About Management Interface Audit Logging

When audit logging is enabled, all operations performed using the Management Console, Management CLI interface, or a custom-written management application, are subject to audit logging.
The audit log entries are stored in JSON format and, based on your configuration, can be stored in files, sent to a syslog server or both. Audit logging can only be configured using the Management CLI and is disabled by default.
Login and logout events cannot be audited as there is no 'authenticated session' in EAP. Instead. audit messages are logged when an operation is received from the user.

Note

By default, audit logging is not active. Audit logging can only be configured using the Management CLI.
To list all available management interface audit logging configuration options and their current values, enter the following Management CLI command.

Note

Add the prefix /host=HOST_NAME to the command for a managed domain.
[... /] /core-service=management/access=audit:read-resource(recursive=true)

3.7.2. Enable Management Interface Audit Logging to a File

To enable audit logging output to a file, enter the following Management CLI command.

Note

If the change is to be applied to a managed domain, add the prefix /host=HOST_NAME to the following command.
/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
Management operations are now logged to a file:
  • Standalone mode: EAP_HOME/standalone/data/audit-log.log
  • Domain mode: EAP_HOME/domain/data/audit-log.log
For details of all file handler attributes, see Section A.3, “Management Interface Audit Logging Reference”.

3.7.3. Enable Management Interface Audit Logging to a Syslog Server

By default, audit logging is preconfigured to output to a file when enabled. This procedure configures output to a syslog server and enables audit logging to a file. For details of all syslog handler attributes see Section A.3, “Management Interface Audit Logging Reference”.

Note

If the change is to be applied to a managed domain, add the prefix /host=HOST_NAME to the /core-service commands.

Procedure 3.24. Enable Audit Logging to a Syslog Server

  1. Enable Audit Logging

    Execute the following command:
    [.. /]/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
  2. Create a syslog Handler

    In this example the syslog server is running on the same server as the JBoss EAP instance, on port 514. Replace the values of the host attribute with values appropriate to your environment.

    Example 3.34. Example syslog handler

    [.. /]batch
    [.. / #]/core-service=management/access=audit/syslog-handler=mysyslog:add(formatter=json-formatter)
    [.. / #]/core-service=management/access=audit/syslog-handler=mysyslog/protocol=udp:add(host=localhost,port=514)
    [.. /]run-batch
  3. Add a Reference to the syslog Handler

    Execute the following:
    [.. /]/core-service=management/access=audit/logger=audit-log/handler=mysyslog:add
Result
Management interface audit log entries are logged on the syslog server.

Note

Enabling audit logging to a Syslog Server in JBoss EAP will not work unless logging is enabled in the operating system as well.
For more information on rsyslog configurations on Red Hat Enterprise Linux, refer to the "Basic Configuration of rsyslog" section in the System Administrator's Guide for Red Hat Enterprise Linux in https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/

3.7.4. Disable Management Interface Audit Logging

The audit logging to a file or a syslog server can be disabled by executing the following command:
/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=false)

3.7.5. Read a Management Interface Audit Log

Audit log entries output to file(s) are best viewed with a text viewer, while those output to a syslog server are best viewed using a syslog viewer application.

Note

Using a text editor for viewing log files is not recommended as some may prevent further log entries being written to the log file.
The management interface audit logs are output in JSON format. Each log entry begins with an optional timestamp, then the fields listed in the Management Interface Audit Log Fields table.

Table 3.5. Management Interface Audit Log Fields

Field Name Description
type This can have the values core, meaning it is a management operation, or jmx meaning it comes from the JMX subsystem (see the JMX subsystem for configuration of the JMX subsystem's audit logging).
r/o Has the value true if the operation does not change the management model, false otherwise.
booting Has the value true if the operation was executed during the bootup process, false if it was executed once the server is up and running.
version The version number of the JBoss EAP instance.
user The username of the authenticated user. If the operation occurs via the Management CLI on the same machine as the running server, the special user $local is used.
domainUUID An ID to link together all operations as they are propagated from the domain controller to its servers, slave host controllers, and slave host controller servers.
access This can have one of the following values:
  • NATIVE - The operation came in through the native management interface, for example the Management CLI.
  • HTTP - The operation came in through the domain HTTP interface, for example the Management Console.
  • JMX - The operation came in through the JMX subsystem. See JMX for how to configure audit logging for JMX.
remote-address The address of the client executing this operation.
success Has the value true if the operation is successful, false if it was rolled back.
ops The operations being executed. This is a list of the operations serialized to JSON. At boot this is the operations resulting from parsing the XML. Once booted the list typically contains a single entry.

Chapter 4. User Management

4.1. About JBoss EAP User Management

Depending on how JBoss EAP 6 is installed, there may be no user accounts initially available to access the management interfaces.
If you install the platform using a graphical installer, only one user account with the necessary privileges to access the JBoss EAP 6 management interfaces is created during the installation.
If you install the platform manually using a ZIP archive no user accounts with appropriate privileges are created during installation.
If you install the platform manually using the JAR installer at a console, one user account with appropriate privileges is created during installation.
HTTP-based communication with JBoss EAP 6 is considered remote access, even if the traffic originates on the localhost. Therefore, you must create at least one administrative user 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.
This guide covers simple user management for JBoss EAP 6 using the add-user.sh script. For more advanced authentication and authorization options, such as LDAP or Role-Based Access Control (RBAC), see the Core Management Authentication section of the JBoss EAP Security Architecture document.

4.2. User Creation

4.2.1. Add the User for the Management Interfaces

The following procedure documents how to create the initial administrative user, in the event such a user is not created by the chosen installation method. This initial administrative user can use the web-based Management Console and remote instances of the Management CLI to configure and administer JBoss EAP 6 from remote systems.

Procedure 4.1. Create the Initial Administrative User for the Remote Management Interfaces

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

    Press ENTER to select the default 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. Enter the desired username and password.

    When prompted, enter the username and password. You will be prompted to confirm the password.
  4. Enter group information.

    Add the group or groups to which the user belongs. If the user belongs to multiple groups, enter a comma-separated list. Leave it blank if you do not want the user to belong to any groups.
  5. Review the information and confirm.

    You are prompted to confirm the information. If you are satisfied, type yes.
  6. Choose whether the user represents a remote JBoss EAP 6 server instance.

    Besides administrators, the other type of user which occasionally needs to be added to JBoss EAP 6 in the ManagementRealm is a user representing another instance of JBoss EAP 6, which must 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.
  7. 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.
  8. 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
  9. You can suppress the normal output of the add-user script by passing the --silent parameter. This applies only if the minimum parameters username and password have been specified. Error messages will still be shown.
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 EAP 6 from remote systems.

4.2.2. Pass Arguments to the User Management add-user Script

You can run the add-user.sh or add-user.bat command interactively or you can pass the arguments on the command line. This section describes the options available when passing command line arguments to the add-user script.
For a comprehensive list of the command line arguments available for the add-user.sh or add-user.bat command. see Section 4.2.3, “Add-user Command Arguments” .
For information on how to specify an alternate properties file and location, see Section 4.2.4, “Specify Alternate Properties Files for User Management Information” .

4.2.3. Add-user Command Arguments

The following table describes the arguments available for the add-user.sh or add-user.bat command.

Table 4.1. Add-user Command Arguments

Command Line Argument Argument Value Description
-a
N/A
This argument specifies to create a user in the application realm. If omitted, the default is to create a user in the management realm.
-dc
DOMAIN_CONFIGURATION_DIRECTORY
This argument specifies the domain configuration directory that will contain the properties files. If it is omitted, the default directory is EAP_HOME/domain/configuration/.
-sc
SERVER_CONFIGURATION_DIRECTORY
This argument specifies an alternate standalone server configuration directory that will contain the properties files. If it is omitted, the default directory is EAP_HOME/standalone/configuration/.
-up
--user-properties
USER_PROPERTIES_FILE
This argument specifies the name of the alternate user properties file. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.
-g
--group
GROUP_LIST
A comma-separated list of groups to assign to this user.
-gp
--group-properties
GROUP_PROPERTIES_FILE
This argument specifies the name of the alternate group properties file. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.
-p
--password
PASSWORD
The password of the user. The password must satisfy the following requirements:
  • It must contain at least 8 characters.
  • It must contain at least one alphabetic character.
  • It must contain at least one digit.
  • It must contain at least one non-alphanumeric symbol
-u
--user
USER_NAME
The name of the user. Only alphanumeric characters and the following symbols are valid: ,./=@\.
-r
--realm
REALM_NAME
The name of the realm used to secure the management interfaces. If omitted, the default is ManagementRealm.
-s
--silent
N/A
Run the add-user script with no output to the console.
-h
--help
N/A
Display usage information for the add-user script.

4.2.4. Specify Alternate Properties Files for User Management Information

Overview
By default, user and role information created using the add-user.sh or add-user.bat script are stored in properties files located in the server configuration directory. The server configuration information is stored in the EAP_HOME/standalone/configuration/ directory and the domain configuration information is stored in the EAP_HOME/domain/configuration/ directory. This topic describes how to override the default file names and locations.
Specify Alternate Properties Files
  • To specify an alternate directory for the server configuration, use the -sc argument. This argument specifies an alternate directory that will contain the server configuration properties files.
  • To specify an alternate directory for the domain configuration, use the -dc argument. This argument specifies an alternate directory that will contain the domain configuration properties files.
  • To specify an alternate user configuration properties file, use the -up or --user-properties argument. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.
  • To specify an alternate group configuration properties file, use the -gp or --group-properties argument. It can be an absolute path or it can be a file name used in conjunction with the -sc or -dc argument that specifies the alternate configuration directory.

Note

The add-user command is intended to operate on existing properties files. Any alternate properties files specified in command line arguments must exist or you will see the following error:
JBAS015234: No appusers.properties files found
For more information about command arguments, see Section 4.2.3, “Add-user Command Arguments” .

4.3. Add-user Script Command Line Examples

4.3.1. Create a User Belonging to a Single Group Using the Default Properties Files

Example 4.1. Create a user belonging to a single group

EAP_HOME/bin/add-user.sh -a -u 'appuser1' -p 'password1!' -g 'guest'
This example gives the following results.
  • The user appuser1 is added to the following default properties files that store user information.
    EAP_HOME/standalone/configuration/application-users.properties
    EAP_HOME/domain/configuration/application-users.properties
  • The user appuser1 with group guest is added to the default properties files that store group information.
    EAP_HOME/standalone/configuration/application-roles.properties
    EAP_HOME/domain/configuration/application-roles.properties

4.3.2. Create a User Belonging to Multiple Groups Using the Default Properties Files

Example 4.2. Create a user belonging to multiple groups

EAP_HOME/bin/add-user.sh -a -u 'appuser1' -p 'password1!' -g 'guest,app1group,app2group'
This example gives the following results.
  • The user appuser1 is added to the following default properties files that store user information.
    EAP_HOME/standalone/configuration/application-users.properties
    EAP_HOME/domain/configuration/application-users.properties
  • The user appuser1 with groups guest, app1group, and app2group is added to the default properties files that store group information.
    EAP_HOME/standalone/configuration/application-roles.properties
    EAP_HOME/domain/configuration/application-roles.properties

4.3.3. Create a User With Administrator Privileges in the Default Realm Using the Default Properties Files

Example 4.3. Create a user with Administrator privileges in the Default Realm

EAP_HOME/bin/add-user.sh -u 'adminuser1' -p 'password1!' -g 'admin'
This example gives the following results.
  • The user adminuser1 is added to the following default properties files that store user information.
    EAP_HOME/standalone/configuration/mgmt-users.properties
    EAP_HOME/domain/configuration/mgmt-users.properties
  • The user adminuser1 with group admin is added to the default properties files that store group information.
    EAP_HOME/standalone/configuration/mgmt-groups.properties
    EAP_HOME/domain/configuration/mgmt-groups.properties

4.3.4. Create a User Belonging to Single Group Using Alternate Properties Files to Store the Information

Example 4.4. Create a user belonging to single group using alternate properties files

EAP_HOME/bin/add-user.sh -a -u appuser1 -p password1! -g app1group -sc /home/someusername/userconfigs/ -up appusers.properties -gp appgroups.properties 
This example gives the following results.
  • The user appuser1 is added to the following properties file and that file is now the default file to store user information.
    /home/someusername/userconfigs/appusers.properties
  • The user appuser1 with group app1group is added to the following properties file and that file is now the default file to store group information.
    /home/someusername/userconfigs/appgroups.properties

Chapter 5. Network and Port Configuration

5.1. Interfaces

5.1.1. About Interfaces

JBoss EAP uses named interface references throughout the configuration. This gives the configuration the ability to reference individual interface declarations with logical names, rather than requiring 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 logical names, each server instance can correspond to a logical name group, allowing for easier interface group administration.
Network interfaces are declared by specifying a logical name and a selection criteria for the physical interface.
The JBoss EAP default configuration includes both a management and public interface names. The management interface name can be used for all components and services that require the management layer, including the HTTP Management Endpoint. The public interface name can be used for all application-related network communications, including Web and Messaging.
The use of default names is not compulsory. New logical names can be created and substituted for default names.
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 or more characteristics that an interface or address must have in order to be a valid match.
The three configuration files remain directly editable but manual edits are no longer required. The Management CLI and Management Console provide a safe, controlled and persistent environment for configuration changes.
The following examples show multiple possible configurations of interface declarations, typically defined in either the standalone.xml or host.xml configuration files. Using these files allow remote host groups to maintain specific interface attributes, while still allowing references to domain controller interfaces.
The following 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>
The following example shows a global interface group. It 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 (eth0) under a relative group called external.

Example 5.3. An external group created with an NIC value

<interface name="external">
   <nic name="eth0"/>
</interface>
The following example declares the default group with requirements. These requirements set the conditions for the interface to be a valid match. This is an example of how JBoss EAP allows for the creation of interface declaration groups with specific properties that can then be referenced using the interface’s name. This helps in reducing configuration complexity and administration overhead 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>

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. Use the Management Console or Management CLI to configure additional attributes and values, as listed in the table below. The relative interface bindings can be replaced with specific values as required but 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>
While running multiple servers in a managed domain, interface binding can be assigned to individual servers in their respective host.xml files. For example:
<servers>
  <server name="server-name" group="main-server-group">
    <interfaces>
      <interface name="public">
        <inet-address value="ip-address"/>
      </interface>
    </interfaces>
  </server>
</servers>

Note

For the above example, substitute server-name with your actual server name and substitute ip-address with your actual IP address.

Table 5.1. Interface Attributes and Values

Interface Element Description
any Element indicating that part of the selection criteria for an interface should be that it meets at least one, but not necessarily all, of the nested set of 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 an 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-address type 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 Element indicating that part of the selection criteria for an interface should be that it does not meet any of the nested set of 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

    • Configure Interface Attributes with the Management CLI

      You can use tab completion to complete the command string as you type, as well as to expose the available attributes.
      Use the Management CLI to add a new server and configure instances to it, effectively adding the same piece of configuration to the XML. Substitute server-name with your actual server name and substitute ip-address with your actual IP address.
      /host=master/server-config=server-name:add(group=main-server-group)
      /host=master/server-config=server-name/interface=public:add(inet-address=ip-address)
      Use the Management CLI to add new interfaces and write new values to the interface attributes.
      1. Add a New Interface

        The add operation creates new interfaces as required. The add command runs from the root of the Management CLI session, and in the following example it 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

        The write-attribute operation writes new values to an attribute. The following example updates the inet-address value to 12.0.0.8.
        /interface=interfacename/:write-attribute(name=inet-address, value=12.0.0.8)
      3. Verify Interface Attributes

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

      1. Log into the Management Console.

        Log into the Management Console of your Managed Domain or Standalone Server instance.
      2. Navigate to Configuration tab

        Select the Configuration tab from the top of the screen.

        Note

        For Domain Mode, select a profile from the Profile drop-down menu at the top left of the screen.
      3. Select Interfaces from the Navigation Menu.

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

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

        1. Select the interface that you need to edit from the Available Interfaces list and click Edit.
        2. Enter required values for Name, Inet Address and Address Wildcard.
        3. Click Save.

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 EAP 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" port-offset="${jboss.socket.binding.port-offset:0}">
        <socket-binding name="management-native" interface="management" port="${jboss							.management.native.port:9999}"/>
        <socket-binding name="management-http" interface="management" port="${jboss								.management.http.port:9990}"/>
        <socket-binding name="management-https" interface="management" port="${jboss							.management.https.port:9443}"/>
        <socket-binding name="ajp" port="8009"/>
        <socket-binding name="http" port="8080"/>
        <socket-binding name="https" port="8443"/>
        <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>

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="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="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="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="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. A 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 a 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

Attribute 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 If the socket will be used for multicast, the multicast port to use. Optional
fixed-port If true, declares that the value of port must always be used for the socket and should not be overridden by applying an increment or decrement. 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 a 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-attribute 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. Navigate to the Configuration tab.

        Select the Configuration tab at the top of the screen.
      3. Select the Socket Binding item from the navigation menu.

        Expand the General Configuration menu. Select Socket Binding. If you are using a managed domain, select the desired group in the Socket Binding Groups list.
      4. Add a New Socket Binding

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

        1. Select a socket binding from the list and click Edit.
        2. Enter any required values such as Name, Interface or Port.
        3. Click Save to finish.

5.2.3. Network Ports Used By JBoss EAP 6

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

Note

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

The default socket binding groups

  • full-ha-sockets
  • full-sockets
  • ha-sockets
  • standard-sockets
These socket binding groups are available only in domain.xml. The standalone server profiles contain only standard socket binding group. This group corresponds to standard-sockets in standalone.xml, ha-sockets for standalone-ha.xml, full-sockets for standalone-full.xml, and full-ha-sockets for standalone-full-ha.xml. Standalone profiles contain some more socket bindings, for example, management-{native,http,https}.

Table 5.3. Reference of the default socket bindings

Name Port Multicast 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. Not configurable using the Management Interfaces. 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 Multicast 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 JBoss EAP 6 and the HTTP load balancer. Yes No Yes No
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 transaction 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
Additionally, if HTTPS is enabled for the Management Console, 9443 is also opened as the default port.

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-attribute 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. A restart is required for the changes to take effect.
        [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 Domain tab

        Select the Domain tab at the top of the screen.
      3. Edit Port Offset Attributes

        1. Select the server under the Available Server Configurations list and click Edit at the top of the attibutes list below.
        2. Enter any desired values in the Port Offset field.
        3. Click Save to finish.

5.3. IPv6

5.3.1. Configure JVM Stack Preferences for IPv6 Networking

Summary
This topic covers enabling IPv6 networking for the JBoss EAP 6 installation.

Procedure 5.1. Disable the IPv4 Stack Java Property

  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:

    Example 5.8. JVM options

    # 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

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

Procedure 5.2. Configure the Interface for IPv6 Networking

  1. Select the Configuration tab at the top of the screen.
  2. Expand the General Configuration menu and select Interfaces.
  3. Select the interface from the Available Interfaces list.
  4. Click Edit in the detail list.
  5. Set the inet address to:
    ${jboss.bind.address.management:[ADDRESS]}
  6. Click Save to finish.
  7. Restart the server to implement the changes.

5.3.3. Configure JVM Stack Preferences for IPv6 Addresses

Summary
This topic covers configuring the JBoss EAP 6 installation to prefer IPv6 addresses through the configuration files.

Procedure 5.3. Configure the JBoss EAP 6 Installation to Prefer IPv6 Addresses

  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:

    Example 5.9. JVM options

    # 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.4. Remoting

5.4.1. Configuration of Message Size in Remoting

The remoting subsystem provides the option to limit the size of the messages for remoting protocols. You can set the maximum inbound message size (MAX_INBOUND_MESSAGE_SIZE) and the maximum outbound message size (MAX_OUTBOUND_MESSAGE_SIZE) to ensure that messages are received and sent within appropriate size limits.
The MAX_INBOUND_MESSAGE_SIZE and MAX_OUTBOUND_MESSAGE_SIZE can be set in ejb3 subsystem, and the value is in byte.
<subsystem xmlns="urn:jboss:domain:ejb3:1.5">
......
	<remote connector-ref="remoting-connector" thread-pool-name="default">
		<channel-creation-options>
			<option name="MAX_INBOUND_MESSAGE_SIZE" value="xxxxx" type="remoting"/>
			<option name="MAX_OUTBOUND_MESSAGE_SIZE" value="xxxxx" type="remoting"/>
		</channel-creation-options>
	</remote>
......
</subsystem>
Configuring the size of messages in remoting protocols helps in effective utilization of system memory and prevents it from reaching an out of memory state while performing important operations.
If the sender sends a message which exceeds the maximum allowable limit (MAX_OUTBOUND_MESSAGE_SIZE), the server throws an exception and cancels the transmission of data. However the connection remains open and the sender can choose to close the message if needed.
If a message received exceeds the maximum allowable limit (MAX_INBOUND_MESSAGE_SIZE) the message is closed asynchronously with the connection still open.

5.4.2. Configure the Remoting Subsystem

Overview
JBoss Remoting has three top-level configurable elements: the worker thread pool, one or more connectors, and a series of local and remote connection URIs. This topic presents an explanation of each configurable item, example CLI commands for how to configure each item, and an XML example of a fully-configured subsystem. This configuration only applies to the server. Most people will not need to configure the Remoting subsystem at all, unless they use custom connectors for their own applications. Applications which act as Remoting clients, such as EJBs, need separate configuration to connect to a specific connector.

Note

The Remoting subsystem configuration is not exposed to the web-based Management Console, but it is fully configurable from the command-line based Management CLI. Editing the XML by hand is not recommended.
Adapting the CLI Commands
The CLI commands are formulated for a managed domain, when configuring the default profile. To configure a different profile, substitute its name. For a standalone server, omit the /profile=default part of the command.
Configuration Outside the Remoting Subsystem
There are a few configuration aspects which are outside of the remoting subsystem:
Network Interface
The network interface used by the remoting subsystem is the public interface defined in the domain/configuration/domain.xml or standalone/configuration/standalone.xml.
<interfaces>
   <interface name="management"/>
   <interface name="public"/>
   <interface name="unsecure"/>
</interfaces>        
            
The per-host definition of the public interface is defined in the host.xml in the same directory as the domain.xml or standalone.xml. This interface is also used by several other subsystems. Exercise caution when modifying it.
<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">
      <!-- Used for IIOP sockets in the standard configuration.
         To secure JacORB you need to setup SSL -->
      <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/>
   </interface>
</interfaces>             
                 
socket-binding
The default socket-binding used by the remoting subsystem binds to TCP port 4447. Refer to the documentation about socket bindings and socket binding groups for more information if you need to change this.
Information about socket binding and socket binding groups can be found in the Socket Binding Groups chapter of JBoss EAP's Administration and Configuration Guide available at https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/?version=6.4
Remoting Connector Reference for EJB
The EJB subsystem contains a reference to the remoting connector for remote method invocations. The following is the default configuration:
<remote connector-ref="remoting-connector" thread-pool-name="default"/>            
            
Secure Transport Configuration
Remoting transports use StartTLS to use a secure (HTTPS, Secure Servlet, etc) connection if the client requests it. The same socket binding (network port) is used for secured and unsecured connections, so no additional server-side configuration is necessary. The client requests the secure or unsecured transport, as its needs dictate. JBoss EAP 6 components which use Remoting, such as EJBs, the ORB, and the JMS provider, request secured interfaces by default.

Warning

StartTLS works by activating a secure connection if the client requests it, and otherwise defaulting to an unsecured connection. It is inherently susceptible to a Man in the Middle style exploit, wherein an attacker intercepts the client's request and modifies it to request an unsecured connection. Clients must be written to fail appropriately if they do not receive a secure connection, unless an unsecured connection actually is an appropriate fall-back.
Worker Thread Pool
The worker thread pool is the group of threads which are available to process work which comes in through the Remoting connectors. It is a single element <worker-thread-pool>, and takes several attributes. Tune these attributes if you get network timeouts, run out of threads, or need to limit memory usage. Specific recommendations depend on your specific situation. Contact Red Hat Global Support Services for more information.

Table 5.4. Worker Thread Pool Attributes

Attribute Description CLI Command
read-threads
The number of read threads to create for the remoting worker. Defaults to 1.
/profile=default/subsystem=remoting/:write-attribute(name=worker-read-threads,value=1)
write-threads
The number of write threads to create for the remoting worker. Defaults to 1.
/profile=default/subsystem=remoting/:write-attribute(name=worker-write-threads,value=1)
task-keepalive
The number of milliseconds to keep non-core remoting worker task threads alive. Defaults to 60.
/profile=default/subsystem=remoting/:write-attribute(name=worker-task-keepalive,value=60)
task-max-threads
The maximum number of threads for the remoting worker task thread pool. Defaults to 16.
/profile=default/subsystem=remoting/:write-attribute(name=worker-task-max-threads,value=16)
task-core-threads
The number of core threads for the remoting worker task thread pool. Defaults to 4.
/profile=default/subsystem=remoting/:write-attribute(name=worker-task-core-threads,value=4)
task-limit
The maximum number of remoting worker tasks to allow before rejecting. Defaults to 16384.
/profile=default/subsystem=remoting/:write-attribute(name=worker-task-limit,value=16384)
Connector
The connector is the main Remoting configuration element. Multiple connectors are allowed. Each consists of a element <connector> element with several sub-elements, as well as a few possible attributes. The default connector is used by several subsystems of JBoss EAP 6. Specific settings for the elements and attributes of your custom connectors depend on your applications, so contact Red Hat Global Support Services for more information.

Table 5.5. Connector Attributes

Attribute Description CLI Command
socket-binding The name of the socket binding to use for this connector.
/profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=socket-binding,value=remoting)
authentication-provider
The Java Authentication Service Provider Interface for Containers (JASPIC) module to use with this connector. The module must be in the classpath.
/profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=authentication-provider,value=myProvider)
security-realm
Optional. The security realm which contains your application's users, passwords, and roles. An EJB or Web Application can authenticate against a security realm. ApplicationRealm is available in a default JBoss EAP 6 installation.
/profile=default/subsystem=remoting/connector=remoting-connector/:write-attribute(name=security-realm,value=ApplicationRealm)

Table 5.6. Connector Elements

Attribute Description CLI Command
sasl
Enclosing element for Simple Authentication and Security Layer (SASL) authentication mechanisms
N/A
properties
Contains one or more <property> elements, each with a name attribute and an optional value attribute.
/profile=default/subsystem=remoting/connector=remoting-connector/property=myProp/:add(value=myPropValue)
Outbound Connections
You can specify three different types of outbound connection:
  • Outbound connection to a URI.
  • Local outbound connection – connects to a local resource such as a socket.
  • Remote outbound connection – connects to a remote resource and authenticates using a security realm.
All of the outbound connections are enclosed in an <outbound-connections> element. Each of these connection types takes an outbound-socket-binding-ref attribute. The outbound-connection takes a uri attribute. The remote outbound connection takes optional username and security-realm attributes to use for authorization.

Table 5.7. Outbound Connection Elements

Attribute Description CLI Command
outbound-connection Generic outbound connection.
/profile=default/subsystem=remoting/outbound-connection=my-connection/:add(uri=http://my-connection)
local-outbound-connection Outbound connection with a implicit local:// URI scheme.
/profile=default/subsystem=remoting/local-outbound-connection=my-connection/:add(outbound-socket-binding-ref=remoting2)
remote-outbound-connection
Outbound connections for remote:// URI scheme, using basic/digest authentication with a security realm.
/profile=default/subsystem=remoting/remote-outbound-connection=my-connection/:add(outbound-socket-binding-ref=remoting,username=myUser,security-realm=ApplicationRealm)
SASL Elements
Before defining the SASL child elements, you need to create the initial SASL element. Use the following command:
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:add
The child elements of the SASL element are described in the table below.

Table 5.8. SASL child elements

Attribute Description CLI Command
include-mechanisms
Contains a value attribute, which is a list of SASL mechanisms.
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=include-mechanisms,value=["DIGEST","PLAIN","GSSAPI"])
qop
Contains a value attribute, which is a list of SASL Quality of protection values, in decreasing order of preference.
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=qop,value=["auth"])
strength
Contains a value attribute, which is a list of SASL cipher strength values, in decreasing order of preference.
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=strength,value=["medium"])
reuse-session
Contains a value attribute which is a boolean value. If true, attempt to reuse sessions.
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=reuse-session,value=false)
server-auth
Contains a value attribute which is a boolean value. If true, the server authenticates to the client.
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl:write-attribute(name=server-auth,value=false)
policy
An enclosing element which contains zero or more of the following elements, which each take a single value.
  • forward-secrecy – whether mechanisms are required to implement forward secrecy (breaking into one session will not automatically provide information for breaking into future sessions)
  • no-active – whether mechanisms susceptible to non-dictionary attacks are permitted. A value of false permits, and true denies.
  • no-anonymous – whether mechanisms that accept anonymous login are permitted. A value of false permits, and true denies.
  • no-dictionary – whether mechanisms susceptible to passive dictionary attacks are allowed. A value of false permits, and true denies.
  • no-plain-text – whether mechanisms which are susceptible to simple plain passive attacks are allowed. A value of false permits, and true denies.
  • pass-credentials – whether mechanisms which pass client credentials are allowed.
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:add
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=forward-secrecy,value=true)
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-active,value=false)
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-anonymous,value=false)
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-dictionary,value=true)
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=no-plain-text,value=false)
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/sasl-policy=policy:write-attribute(name=pass-credentials,value=true)
properties
Contains one or more <property> elements, each with a name attribute and an optional value attribute.
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/property=myprop:add(value=1)
/profile=default/subsystem=remoting/connector=remoting-connector/security=sasl/property=myprop2:add(value=2)

Example 5.10. Example Configurations

This example shows the default remoting subsystem that ships with JBoss EAP 6.
<subsystem xmlns="urn:jboss:domain:remoting:1.1">
    <connector name="remoting-connector" socket-binding="remoting" security-realm="ApplicationRealm"/>
</subsystem>    
    
This example contains many hypothetical values, and is presented to put the elements and attributes discussed previously into context.
<subsystem xmlns="urn:jboss:domain:remoting:1.1">
    <worker-thread-pool read-threads="1" task-keepalive="60" task-max-threads="16" task-core-thread="4" task-limit="16384" write-threads="1" />
    <connector name="remoting-connector" socket-binding="remoting" security-realm="ApplicationRealm">
        <sasl>
            <include-mechanisms value="GSSAPI PLAIN DIGEST-MD5" />
            <qop value="auth" />
            <strength value="medium" />
            <reuse-session value="false" />
            <server-auth value="false" />
            <policy>
                <forward-secrecy value="true" />
                <no-active value="false" />
                <no-anonymous value="false" />
                <no-dictionary value="true" />
                <no-plain-text value="false" />
                <pass-credentials value="true" />
            </policy>
            <properties>
                <property name="myprop1" value="1" />
                <property name="myprop2" value="2" />
            </properties>
        </sasl>
        <authentication-provider name="myprovider" />
        <properties>
            <property name="myprop3" value="propValue" />
        </properties>
    </connector>
    <outbound-connections>
        <outbound-connection name="my-outbound-connection" uri="http://myhost:7777/"/>
        <remote-outbound-connection name="my-remote-connection" outbound-socket-binding-ref="my-remote-socket" username="myUser" security-realm="ApplicationRealm"/>
        <local-outbound-connection name="myLocalConnection" outbound-socket-binding-ref="my-outbound-socket"/>
    </outbound-connections>
</subsystem>    
    

Configuration Aspects Not Yet Documented

  • JNDI and Multicast Automatic Detection

Chapter 6. Datasource Management

6.1. Introduction
6.1.1. About JDBC
6.1.2. JBoss EAP 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. Database Connection Validation
6.6.1. Configure Database Connection Validation Settings
6.7. Datasource Configuration
6.7.1. Datasource Parameters
6.7.2. Datasource Connection URLs
6.7.3. Datasource Extensions
6.7.4. View Datasource Statistics
6.7.5. Datasource Statistics
6.8. Example Datasources
6.8.1. Example PostgreSQL Datasource
6.8.2. Example PostgreSQL XA Datasource
6.8.3. Example MySQL Datasource
6.8.4. Example MySQL XA Datasource
6.8.5. Example Oracle Datasource
6.8.6. Example Oracle XA Datasource
6.8.7. Example Microsoft SQLServer Datasource
6.8.8. Example Microsoft SQLServer XA Datasource
6.8.9. Example IBM DB2 Datasource
6.8.10. Example IBM DB2 XA Datasource
6.8.11. Example Sybase Datasource
6.8.12. Example Sybase XA Datasource

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.

Procedure 6.1. Test datasource pools connection using Management Console

  1. Select the Runtime tab from the top of the Management Console.
  2. Expand the Subsystems menu on the left, and select Datasources.
  3. Click the Test Connection button to test the connection to the datasource and verify the settings are correct.

Procedure 6.2. Test datasource connection using Management CLI

  1. Launch the CLI tool and connect to your server.
  2. Run the following Management CLI command to test the connection:
    • In Standalone mode, enter the following command:
      /subsystem=datasources/data-source=ExampleDS:test-connection-in-pool
      
    • In Domain mode, enter the following command:
      host=master/server=server-one/subsystem=datasources/data-source=ExampleDS:test-connection-in-pool
To get started with JDBC and datasources, refer to the JDBC Driver section of the Administration and Configuration Guide for JBoss EAP 6.

6.1.2. JBoss EAP 6 Supported Databases

The list of JDBC compliant databases supported by JBoss EAP 6 is available here: https://access.redhat.com/articles/111663.

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 EAP 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 EAP 6 Supported Databases”.

6.1.5. Deployment of -ds.xml files

In JBoss EAP 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 EAP 6, following the 1.1 data sources schema available under Schemas here: http://www.ironjacamar.org/documentation.html.

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. This feature is deprecated in JBoss EAP 6.4 and will not be supported in the next major release of the product.

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 JBoss EAP 6 can use them. JBoss EAP 6 allows you to deploy these drivers like any other deployment. This means that you can deploy them across multiple servers in a server group, if you use a managed domain.
Prerequisites
Before performing this task, you need to meet the following prerequisites:
  • Download the JDBC driver from your database vendor.

Note

Any JDBC 4-compliant driver is automatically recognized and installed in the system by name and version. A JDBC JAR is identified using the Java service provider mechanism. Such JARs contain the META-INF/services/java.sql.Driver text, which contains the name of the Driver classes in that JAR.

Procedure 6.3. Modify the JDBC Driver JAR

If the JDBC driver JAR is not JDBC 4-compliant, it can be made deployable using the following method.
  1. Change to, or create, an empty temporary directory.
  2. Create a META-INF subdirectory.
  3. Create a META-INF/services subdirectory.
  4. Create a META-INF/services/java.sql.Driver file, which contains one line indicating the fully-qualified class name of the JDBC driver.
  5. Use the JAR command-line tool to update the JAR like this:
    jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver
  6. If you use a managed domain, deploy the JAR file to a server group. Otherwise, deploy it to your server. See Section 10.2.2, “Enable a Deployed 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.4. Install a JDBC Driver as a Core Module Using the Management CLI

  1. Start the Server.
  2. Start the Management CLI, but do not use the --connect or -c argument to connect to the running instance.
  3. Use the module add CLI command to add the new module.

    Example 6.1. Example CLI command to add a MySQL JDBC driver module

    module add --name=com.mysql --resources=/path/to/mysql.jar --dependencies=javax.api,javax.transaction.api

    Note

    Using the module management CLI command to add and remove modules is provided as technology preview only, and should not be used to add modules to a remote JBoss EAP instance. Modules should be added and removed manually in a production environment.
    Perform the following steps to add a module manually.
    1. A file path structure will be created under the EAP_HOME/modules/ directory. For example, for a MySQL JDBC driver, the following will be created: EAP_HOME/modules/com/mysql/main/.
    2. The JAR files specified as resources will be copied to the main/ subdirectory.
    3. A module.xml file with the specified dependencies will be created in the main/ subdirectory. See Section 7.1.1, “Modules” for an example of a module.xml file.
    Execute module --help for more details on using this command to add and remove modules.
  4. Use the connect CLI command to connect to the running instance.
  5. Run the CLI command to add the JDBC driver module to the server configuration.
    The command you choose depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. For example, the /META-INF/services/java.sql.Driver file in the MySQL 5.1.20 JDBC JAR lists two classes:
    • com.mysql.jdbc.Driver
    • com.mysql.fabric.jdbc.FabricMySQLDriver
    When there is more than one entry, you must also specify the name of the driver class. Failure to do so results in an error similar to the following:

    Example 6.2. Driver class error

    JBAS014749: Operation handler failed: Service jboss.jdbc-driver.mysql is already registered
    • Run the CLI command for JDBC JARs containing one class entry.
      /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.3. CLI Command for Standalone Mode for JDBC JARs with one driver class

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

      Example 6.4. CLI Command for Domain Mode for JDBC JARs with one driver class

      /profile=ha/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)
    • Run the CLI command for JDBC JARs containing multiple class entries.
      /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, driver-class-name=DRIVER_CLASS_NAME)

      Example 6.5. CLI Command for Standalone Mode for JDBC JARs with multiple driver class entries

      /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, driver-class-name=com.mysql.jdbc.Driver)

      Example 6.6. CLI Command for Domain Mode for JDBC JARs with multiple driver class entries

      /profile=ha/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, driver-class-name=com.mysql.jdbc.Driver)

      Example 6.7. CLI Command for Domain Mode for JDBC JARs with multiple non-XA driver class entries

      /profile=ha/subsystem=datasources/jdbc-driver=oracle/:add(driver-module-name=com.oracle,driver-name=oracle,jdbc-compliant=true,driver-datasource-class-name=oracle.jdbc.OracleDriver)
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 JBoss EAP 6.

Note

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.5. Add a Dependency to the Application

You can add a dependency to an application using either of the following methods. Choose whichever method you prefer.
    • 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.8. MANIFEST.MF file with com.mysql declared as a 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.9. jboss-deployment-structure.xml file with com.mysql declared as a dependency

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

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

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 EAP 6 server must be running.

Note

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.

Note

To prevent issues such as duplication of driver listing, selected driver not available in a profile, or driver not displayed if a server for the profile is not running, in JBoss EAP 6.4 onwards, only JDBC drivers that are installed as modules and correctly referenced from profiles are detectable while creating a datasource using the Management Console in domain mode.

Procedure 6.6. Create a Datasource using either the Management CLI or the Management Console

    • Management CLI

      1. Launch the CLI tool and connect to your server.
      2. Run the following Management CLI command to create a non-XA datasource, configuring the variables as appropriate:

        Note

        The value for DRIVER_NAME depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. If there is only one class, the value is the name of the JAR. If there are multiple classes, the value is the name of the JAR + driverClassName + "_" + majorVersion +"_" + minorVersion. Failure to do so will result in the following error being logged:
        JBAS014775:    New missing/unsatisfied dependencies
        For example, the DRIVER_NAME value required for the MySQL 5.1.31 driver, is mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1.
        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

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box in the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources from the menu on the left of the console.
      3. Create a new datasource

        1. Click Add 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 click Next to continue.
        4. Enter the connection settings in the Create Datasource wizard.
        5. Click the Test Connection button to test the connection to the datasource and verify the settings are correct.
        6. Click Done to finish
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

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

Note

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.7. Modify a Non-XA Datasource

    • 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

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box in the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources from expanded menu.
      2. Edit the datasource

        1. Select a datasource from the Available Datasources list. The datasource attributes are displayed below.
        2. Click Edit to edit the datasource attributes.
        3. Click Save to finish.
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

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

Procedure 6.8. Remove a Non-XA Datasource

    • 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

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box in the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources.
      2. Select the datasource to be deleted, then click Remove.
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

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

Note

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.9. Create an XA Datasource, Using Either the Management CLI or the Management Console

    • Management CLI

      1. Run the following Management CLI command to create an XA datasource, configuring the variables as appropriate:

        Note

        The value for DRIVER_NAME depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. If there is only one class, the value is the name of the JAR. If there are multiple classes, the value is the name of the JAR + driverClassName + "_" + majorVersion +"_" + minorVersion. Failure to do so will result in the following error being logged:
        JBAS014775:    New missing/unsatisfied dependencies
        For example, the DRIVER_NAME value required for the MySQL 5.1.31 driver, is mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1.
        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

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box at the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources.
      2. Select the XA Datasource tab.
      3. Create a new XA datasource

        1. Click Add.
        2. Enter the new XA datasource attributes in the Create XA Datasource wizard and click Next.
        3. Enter the JDBC driver details in the Create XA Datasource wizard and click Next.
        4. Enter the XA properties and click Next.
        5. Enter the connection settings in the Create XA Datasource wizard.
        6. Click the Test Connection button to test the connection to the XA datasource and verify the settings are correct.
        7. Click Done to finish
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

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

Procedure 6.10. Modify an XA Datasource, Using Either the Management CLI or the Management Console

    • 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

        1. Select the Configuration tab from the top of the console.
        2. For Domain Mode only, select a profile from the drop-down box at top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources.
      2. Select the XA Datasource tab.
      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

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

Procedure 6.11. Remove an XA Datasource Using Either the Management CLI or the Management Console

    • 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

        1. Select the Configuration tab from the top of the console.
        2. For Domain mode only, select a profile from the drop-down box in the top left.
        3. Expand the Subsystems menu on the left of the console, then expand the Connector menu.
        4. Select Datasources.
      2. Select the XA Datasource tab.
      3. Select the registered XA datasource to be deleted, and click Remove to permanently delete the XA datasource.
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 EAP 6 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.

Note

The names used in the Table 6.2, “General Configuration Attributes” are parameters which are used when the datasource is configured via CLI. They may differ from names used in XML configuration file.

Vendor-Specific Configuration Information

This section describes specific configurations which are required to be done for particular database to cooperate in XA transactions managed by the JBoss EAP transaction manager. For more detailed information, refer to documentation for a particular database.
Oracle
If the Oracle datasource is configured incorrectly, you may see errors like the following in your log output:

Example 6.11. Incorrect configuration error

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.

Example 6.12. Grant configuration

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 and Postgres Plus Advanced Server
For PostgreSQL to be able to handle XA transaction, change the configuration parameter max_prepared_transactions to an value higher than 0.
MySQL
No special configuration is required. For more information, refer to MySQL documentation.
IBM DB2
No special configuration is required. For more information, refer to IBM DB2 documentation.
Sybase
Sybase expects XA transactions to be enabled on the database. Without correct database configuration, XA transactions will not work. enable xact coordination enables or disables Adaptive Server transaction coordination services. When this parameter is enabled, Adaptive Server ensures that updates to remote Adaptive Server data commit or roll back with the original transaction. To enable transaction coordination, use:
sp_configure 'enable xact coordination', 1
.
MSSQL
For more information, refer to Microsoft documentation. You can also refer http://msdn.microsoft.com/en-us/library/aa342335.aspx as a starting point.

Vendor-specific issues and their consequences

This section describes the currently known database specific issues connected with handling XA transactions. These issues refers to database versions and jdbc drivers which are currently supported by particular EAP version.
Oracle
There are no known issues related to database.
PostgreSQL
  • Jdbc driver returns XAER_RMERR when an error occurs during the call of commit method protocol. Database returns this error code and leaves the transaction in in-doubt state on the database side. The correct return code should be XAER_RMFAIL or XAER_RETRY. For more information, see https://github.com/pgjdbc/pgjdbc/issues/236. This causes the transaction to be left in the Heuristic state on the EAP side and holding locks in database which requires user intervention.
  • The incorrect error code returned by the jdbc driver can cause data inconsistency in some cases. For more information, refer to https://developer.jboss.org/thread/251537, https://github.com/pgjdbc/pgjdbc/issues/236
Postgres Plus Advanced Server
  • Jdbc driver returns XAER_RMERR when an error occurs during the call of commit method protocol. Database returns this error code and leaves the transaction in in-doubt state on the database side. The correct return code should be XAER_RMFAIL or XAER_RETRY. For more information, see https://github.com/pgjdbc/pgjdbc/issues/236. This causes the transaction to be left in the Heuristic state on the EAP side and holding locks in database which requires user intervention.
  • The incorrect error code returned by the jdbc driver can cause data inconsistency in some cases. For more information, refer to https://developer.jboss.org/thread/251537
  • If XAResource.rollback is called for the same XID more than once then XAException is thrown. Calling rollback against the same XID several times is compliant with JTS spec and no XAException should be thrown. For more information, see https://github.com/pgjdbc/pgjdbc/issues/78.
MySQL
MySQL is not capable of handling XA transactions. If a client is disconnected the MySQL then all the information about such transactions is lost. For more information, see http://bugs.mysql.com/bug.php?id=12161.
IBM DB2
There are no known issues related to database.
Sybase
  • Jdbc driver returns XAER_RMERR when an error occurs during the call of commit method protocol. Database returns this error code and leaves the transaction in in-doubt state on the database side. The correct return code should be XAER_RMFAIL or XAER_RETRY. For more information, see https://github.com/pgjdbc/pgjdbc/issues/236. This causes the transaction to be left in the Heuristic state on the EAP side and holding locks in database which requires user intervention.
  • If XAResource.rollback is called for the same XID more than once then XAException is thrown. Calling rollback against the same XID several times is compliant with JTS spec and no XAException should be thrown. For more information, see https://github.com/pgjdbc/pgjdbc/issues/78.
MSSQL
Messaging

IBM Websphere

  • When JTS is used then second call of rollback against the same XID during the periodic recovery can cause an error to be logged in the log file. Second rollback against the same XID is JTS complaint and can be ignored.
    When RAR does not know such XID, then XAER_NOTA return code is expected. But IBM Websphere may return an incorrect return code XAER_RMFAIL.
    The method 'xa_rollback' has failed with errorCode '-7' due to the resource being closed.'

ActiveMQ

  • Resource adapter returns XAER_RMERR when an error occurs during the call of commit method protocol, for example network disconnection. Resource adapter returns this error code back to transaction manager and it causes the transaction being left in in-doubt state on message broker side. This behaviour is against XA specification and the correct return code should be XAER_RMFAIL or XAER_RETRY. The wrong error code can cause data inconsistency in some cases. For more information, refer to https://developer.jboss.org/thread/251537 .
    WARN [com.arjuna.ats.jtax] ...: XAResourceRecord.rollback caused an XA error: ARJUNA016099: Unknown error code:0 from resource ...  in transaction ...: javax.transaction.xa.XAException: Transaction ...  has not been started.

TIBCO

  • When JTS is used then second call of rollback against the same XID during the periodic recovery can cause an error to be logged in the log file. Second rollback against the same XID is JTS complaint and can be ignored.
    WARN [com.arjuna.ats.jtax] ...: XAResourceRecord.rollback caused an XA error: XAException.XAER_RMFAIL from resource ... in transaction ...: javax.transaction.xa.XAException

6.5. Datasource Security

6.5.1. About Datasource Security

Datasource security refers to encrypting or obscuring passwords for datasource connections. These passwords can be stored in plain text in configuration files, however this represents a security risk.
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 the Security Architecture and other JBoss EAP security documentation.

Example 6.13. Security Domain Example

 <security-domain name="DsRealm" cache-type="default">  
  <authentication>  
    <login-module code="ConfiguredIdentity" flag="required">  
      <module-option name="userName" value="sa"/>  
      <module-option name="principal" value="sa"/>  
      <module-option name="password" value="sa"/>  
    </login-module>  
  </authentication>  
</security-domain>  
The DsRealm domain is referenced by a datasource like so:
<datasources>
  <datasource jndi-name="java:jboss/datasources/securityDs"
    pool-name="securityDs">
    <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
      <driver>h2</driver>
      <new-connection-sql>select current_user()</new-connection-sql>
      <security>
        <security-domain>DsRealm</security-domain>
      </security>
    </datasource>
</datasources>

Note

If a security domain will be used with multiple datasources, then caching should be disabled on the security domain. This can be accomplished by setting the value of the cache-type attribute to none or by removing the attribute altogether. However, if caching is desired, then a separate security domain should be used for each datasource.

Example 6.14. Password Vault Example

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

6.6. Database Connection Validation

6.6.1. Configure Database Connection Validation Settings

Overview
Database maintenance, network problems, or other outage events may cause JBoss EAP 6 to lose the connection to the database. You enable database connection validation using the <validation> element within the <datasource> section of the server configuration file. Follow the steps below to configure the datasource settings to enable database connection validation in JBoss EAP 6.

Procedure 6.12. Configure Database Connection Validation Settings

  1. Choose a Validation Method

    Select one of the following validation methods.
    • <validate-on-match>true</validate-on-match>

      When the <validate-on-match> option is set to true, the database connection is validated every time it is checked out from the connection pool using the validation mechanism specified in the next step.
      If a connection is not valid, a warning is written to the log and it retrieves the next connection in the pool. This process continues until a valid connection is found. If you prefer not to cycle through every connection in the pool, you can use the <use-fast-fail> option. If a valid connection is not found in the pool, a new connection is created. If the connection creation fails, an exception is returned to the requesting application.
      This setting results in the quickest recovery but creates the highest load on the database. However, this is the safest selection if the minimal performance hit is not a concern.
    • <background-validation>true</background-validation>

      When the <background-validation> option is set to true, it is used in combination with the <background-validation-millis> value to determine how often background validation runs. The default value for the <background-validation-millis> parameter is 0 milliseconds, meaning it is disabled by default. This value should not be set to the same value as your <idle-timeout-minutes> setting.
      It is a balancing act to determine the optimum <background-validation-millis> value for a particular system. The lower the value, the more frequently the pool is validated and the sooner invalid connections are removed from the pool. However, lower values take more database resources. Higher values result in less frequent connection validation checks and use less database resources, but dead connections are undetected for longer periods of time.

    Note

    If the <validate-on-match> option is set to true, the <background-validation> option should be set to false. The reverse is also true. If the <background-validation> option is set to true, the <validate-on-match> option should be set to false.
  2. Choose a Validation Mechanism

    Select one of the following validation mechanisms.
    • Specify a <valid-connection-checker> Class Name

      This is the preferred mechanism as it optimized for the particular RDBMS in use. JBoss EAP 6 provides the following connection checkers:
      • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
      • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
    • Specify SQL for <check-valid-connection-sql>

      You provide the SQL statement used to validate the connection.
      The following is an example of how you might specify a SQL statement to validate a connection for Oracle:
      <check-valid-connection-sql>select 1 from dual</check-valid-connection-sql>
      For MySQL or PostgreSQL, you might specify the following SQL statement:
      <check-valid-connection-sql>select 1</check-valid-connection-sql>
  3. Set the <exception-sorter> Class Name

    When an exception is marked as fatal, the connection is closed immediately, even if the connection is participating in a transaction. Use the exception sorter class option to properly detect and clean up after fatal connection exceptions. JBoss EAP 6 provides the following exception sorters:
    • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.informix.InformixExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
    • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter

6.7. Datasource Configuration

6.7.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. Note that the logging category jboss.jdbc.spy must also be set to the log level DEBUG in the logging subsystem.
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-selector-strategy-class-name A class that implements interface org.jboss.jca.adapters.jdbc.URLSelectorStrategy.
security
Contains child elements which are security settings. See Table 6.8, “Security parameters”.
validation
Contains child elements which are validation settings. See Table 6.9, “Validation parameters”.
timeout
Contains child elements which are timeout settings. See Table 6.10, “Timeout parameters”.
statement
Contains child elements which are statement settings. See 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. See Table 6.6, “Pool parameters common to non-XA and XA datasources”.
url-delimiter
The delimiter for URLs in a connection-url for High Availability (HA) clustered databases.

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 class loader module which contains the JDBC driver. The accepted format is driverName#majorVersion.minorVersion.
xa-pool
recovery
Contains child elements which are recovery settings. See 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. The default is false.
use-strict-min Whether the idle connection scan should strictly stop marking for closure of any further connections, once the min-pool-size has been reached. The default value is false.
flush-strategy
Whether the pool is 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 accounts 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.
Using this option will cause your total pool size to be twice max-pool-size, because two actual pools will be created.
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 plug-in 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.
Specifying "true" for validate-on-match is typically not done in conjunction with specifying "true" for background-validation. Validate-on-match is needed when a client must have a connection validated prior to use. This parameter is false by default.
background-validation
Specifies that connections are validated on a background thread. Background validation is a performance optimization when not used with validate-on-match. If validate-on-match is true, using background-validation could result in redundant checks. Background validation does leave open the opportunity for a bad connection to be given to the client for use (a connection goes bad between the time of the validation scan and prior to being handed to the client), so the client application must account for this possibility.
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 is broadcast to all instances of javax.resource.spi.ConnectionEventListener as a connectionErrorOccurred message.

Table 6.10. Timeout parameters

Parameter Description
use-try-lock Uses tryLock() instead of lock(). This attempts to obtain the lock for the configured number of seconds, before timing out, rather than failing immediately if the lock is unavailable. Defaults to 60 seconds. As an example, to set a timeout of 5 minutes, set <use-try-lock>300</use-try-lock>.
blocking-timeout-millis The maximum time, in milliseconds, to block while waiting for a connection. After this time is exceeded, an 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. If not specified, the default is 30 minutes. 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 JBoss EAP should cache, instead of close or terminate, the underlying physical statement when the wrapper supplied to the application is closed by application code. 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 the org.jboss.jca.core.spi.recoveryRecoveryPlugin class, to be used for recovery.

6.7.2. Datasource Connection URLs

Table 6.13. Datasource Connection URLs

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:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME

Note

The jdbc:microsoft:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME template does not work with new database.

6.7.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.StaleConnectionChecker <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 EAP 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.OracleStaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker

6.7.4. View Datasource Statistics

You can view statistics from defined datasources for both the jdbc and pool using appropriately modified versions of the commands below:

Example 6.15. CLI for domain mode:

Change /host=master/server=server-one and data-source=ExampleDS according to the environment.
[domain@localhost:9999 /]  /host=master/server=server-one/subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "ActiveCount" => "0",
        "AvailableCount" => "20",
        "AverageBlockingTime" => "0",
        "AverageCreationTime" => "0",
        "CreatedCount" => "0",
        "DestroyedCount" => "0",
        "MaxCreationTime" => "0",
        "MaxUsedCount" => "0",
        "MaxWaitTime" => "0",
        "TimedOut" => "0",
        "TotalBlockingTime" => "0",
        "TotalCreationTime" => "0"
    }
}


Example 6.16. CLI for standalone mode:

Change data-source=ExampleDS according to the environment.
[standalone@localhost:9999 /]  /subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
    "outcome" => "success",
    "result" => {
        "ActiveCount" => "0",
        "AvailableCount" => "20",
        "AverageBlockingTime" => "0",
        "AverageCreationTime" => "0",
        "CreatedCount" => "0",
        "DestroyedCount" => "0",
        "MaxCreationTime" => "0",
        "MaxUsedCount" => "0",
        "MaxWaitTime" => "0",
        "TimedOut" => "0",
        "TotalBlockingTime" => "0",
        "TotalCreationTime" => "0"
    }
}

Note

Ensure you specify the include-runtime=true argument, as all statistics are runtime only information and the default is false.

6.7.5. Datasource Statistics

Core Statistics
The following table contains a list of the supported datasource core statistics:

Table 6.15. Core Statistics

Name Description
ActiveCount
The number of active connections. Each of the connections is either in use by an application or available in the pool
AvailableCount
The number of available connections in the pool.
AverageBlockingTime
The average time spent blocking on obtaining an exclusive lock on the pool. The value is in milliseconds.
AverageCreationTime
The average time spent creating a connection. The value is in milliseconds.
CreatedCount
The number of connections created.
DestroyedCount
The number of connections destroyed.
InUseCount
The number of connections currently in use.
MaxCreationTime
The maximum time it took to create a connection. The value is in milliseconds.
MaxUsedCount
The maximum number of connections used.
MaxWaitCount
The maximum number of requests waiting for a connection at the same time.
MaxWaitTime
The maximum time spent waiting for an exclusive lock on the pool.
TimedOut
The number of timed out connections.
TotalBlockingTime
The total time spent waiting for an exclusive lock on the pool. The value is in milliseconds.
TotalCreationTime
The total time spent creating connections. The value is in milliseconds.
JDBC Statistics
The following table contains a list of the supported datasource JDBC statistics:

Table 6.16. JDBC Statistics

Name Description
PreparedStatementCacheAccessCount
The number of times that the statement cache was accessed.
PreparedStatementCacheAddCount
The number of statements added to the statement cache.
PreparedStatementCacheCurrentSize
The number of prepared and callable statements currently cached in the statement cache.
PreparedStatementCacheDeleteCount
The number of statements discarded from the cache.
PreparedStatementCacheHitCount
The number of times that statements from the cache were used.
PreparedStatementCacheMissCount
The number of times that a statement request could not be satisfied with a statement from the cache.
You can enable Core and JDBC statistics using appropriately modified versions of the following commands:
  • /subsystem=datasources/data-source=ExampleDS/statistics=pool:write-attribute(name=statistics-enabled,value=true)
    
    /subsystem=datasources/data-source=ExampleDS/statistics=jdbc:write-attribute(name=statistics-enabled,value=true)
    

6.8. Example Datasources

6.8.1. Example PostgreSQL Datasource

The example below is a PostgreSQL datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.

Example 6.17. PostSQL datasource configuration

<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>
    	<validate-on-match>true</validate-on-match>
      <background-validation>false</background-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.

Example 6.18. module.xml

<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.8.2. Example PostgreSQL XA Datasource

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.

Example 6.19. PostSQL XA datasource

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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.

Example 6.20. module.xml

<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.8.3. Example MySQL Datasource

The example below is a MySQL datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.

Example 6.21. MySQL datasource configuration

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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.

Example 6.22. module.xml

<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.8.4. Example MySQL XA Datasource

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.

Example 6.23. MySQL XA datasource

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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.

Example 6.24. module.xml

<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.8.5. Example Oracle Datasource

Note

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.
The example below is an Oracle datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.

Example 6.25. Oracle datasource configuration

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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">
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Oracle datasource above.

Example 6.26. module.xml

<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.8.6. Example Oracle XA Datasource

Note

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. The value user is the user defined to connect from JBoss to Oracle:
  • 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; (If using Oracle 10g R2 (patched) or Oracle 11g)
    OR
    GRANT EXECUTE ON sys.dbms_system TO user; (If using an unpatched Oracle version prior to 11g)
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.

Example 6.27. Oracle XA datasource

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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.

Example 6.28. module.xml

<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.8.7. Example Microsoft SQLServer Datasource

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.

Example 6.29. SQLserver datasource configuration

<datasources>
  <datasource jndi-name="java:/MSSQLDS" pool-name="MSSQLDS">
    <connection-url>jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection-url>
    <driver>sqlserver</driver>
    <security>
      <user-name>admin</user-name>
      <password>admin</password>
    </security>
    <validation>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
      <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"></exception-sorter>
    </validation>
  </datasource>
  <drivers>
    <driver name="sqlserver" module="com.microsoft">
  </datasources>
The example below is a module.xml file for the Microsoft SQLServer datasource above.

Example 6.30. module.xml

<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.8.8. Example Microsoft SQLServer XA Datasource

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.

Example 6.31. SQLserver XA datasource

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-validation>
      <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
    	<exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter"></exception-sorter>
    </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.

Example 6.32. module.xml

<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.8.9. Example IBM DB2 Datasource

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.

Example 6.33. IBM DB2 datasource configuration

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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">
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the IBM DB2 datasource above.

Example 6.34. module.xml

<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc4.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.8.10. Example IBM DB2 XA Datasource

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.

Example 6.35. IBM DB2 XA datasource configuration

<datasources>
  <xa-datasource jndi-name="java:/DB2XADS" pool-name="DB2XADS">
    <driver>ibmdb2</driver>
    <xa-datasource-property name="DatabaseName">ibmdb2db</xa-datasource-property>
    <xa-datasource-property name="ServerName">hostname</xa-datasource-property>
    <xa-datasource-property name="PortNumber">port</xa-datasource-property>
    <xa-datasource-property name="DriverType">4</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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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>
      <recover-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>
      </recover-plugin>
    </recovery>
  </xa-datasource>
  <drivers>
    <driver name="ibmdb2" module="com.ibm">
      <xa-datasource-class>com.ibm.db2.jcc.DB2XADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the IBM DB2 XA datasource above.

Example 6.36. module.xml

<module xmlns="urn:jboss:module:1.1" name="com.ibm">
  <resources>
    <resource-root path="db2jcc4.jar"/>
    <resource-root path="db2jcc_license_cisuz.jar"/>
    <resource-root path="db2jcc_license_cu.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

6.8.11. Example Sybase Datasource

The example below is a Sybase datasource configuration. The datasource has been enabled, a user has been added, and validation options have been set.

Example 6.37. Sybase datasource configuration

<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>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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.jdbc4.jdbc.SybDataSource</datasource-class>
      <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Sybase datasource above.

Example 6.38. module.xml

<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.8.12. Example Sybase XA Datasource

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.

Example 6.39. Sybase XA datasource configuration

<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>
    <xa-pool>
      <is-same-rm-override>false</is-same-rm-override>
    </xa-pool>
    <validation>
      <validate-on-match>true</validate-on-match>
      <background-validation>false</background-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.jdbc4.jdbc.SybDataSource</datasource-class>
      <xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xa-datasource-class>
    </driver>
  </drivers>
</datasources>
The example below is a module.xml file for the Sybase XA datasource above.

Example 6.40. module.xml

<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 EAP 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.
Static Modules
Static Modules are predefined in the EAP_HOME/modules/ directory of the application server. Each sub-directory represents one module and defines a main/ subdirectory that contains a configuration file (module.xml) and any required JAR files. 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.

Example 7.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, excluding the main/ subdirectory name.
The modules provided in JBoss EAP distributions are located in a system directory within the EAP_HOME/modules directory. This keeps them separate from any modules provided by third parties.
Any Red Hat provided layered products that layer on top of JBoss EAP 6.1 or later will also install their modules within the system directory.
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.
Users must ensure that custom modules are installed into the EAP_HOME/modules directory, using a one directory per module layout. This ensures that custom versions of modules that already exist in the system directory are loaded instead of the shipped versions. In this way, user provided modules will take precedence over system modules.
If you use the JBOSS_MODULEPATH environment variable to change the locations in which JBoss EAP searches for modules, then the product will look for a system subdirectory structure within one of the locations specified. A system structure must exist somewhere in the locations specified with JBOSS_MODULEPATH.
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 EAP 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 EAP 6.
There are two types of dependencies: explicit and implicit.
Explicit Dependencies
Explicit dependencies are declared by the developer in the configuration file. Static modules can declare dependencies in the module.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
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 EAP 6 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 its 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.2. 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.
See the Class Loading and Modules chapter of the Development Guide for details on using the jboss-deployment-structure.xml deployment descriptor.

7.1.4. Subdeployment Class Loader Isolation

Each subdeployment in an Enterprise Archive (EAR) is a dynamic module with its own class loader. By default a subdeployment can access the resources of other subdeployments.
If a subdeployment is not to be allowed to access the resources of other subdeployments, strict subdeployment isolation can be enabled.

7.2. Disable Subdeployment 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 EAP 6 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.2.
    <profile>
    
       ...
    
       <subsystem xmlns="urn:jboss:domain:ee:1.2" />
    
       ...
    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.2" ></subsystem>
  4. Replace self-closing tags if necessary

    If the EE Subsystem element is a single self-closing tag then replace with appropriate opening and closing tags like this:
    <subsystem xmlns="urn:jboss:domain:ee:1.2" ></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.2" ><ear-subdeployments-isolated>false</ear-subdeployments-isolated></subsystem>
  6. Start the server

    Relaunch the JBoss EAP 6 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.6.1, “Included Modules” for the list of static modules included with JBoss EAP 6. If the module is in another deployment, refer to Section 7.6.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.
    1. Select the Configuration tab from the top of the console.
    2. Domain Mode Only

      1. Select the appropriate profile from the drop-down box in the top left.
    3. Expand the Subsystems menu on the left of the console.
    4. Select ContainerEE from the menu on the left of the console.
  2. Click Add in the Subsystem Defaults section. The Create Module dialog appears.
  3. Type in the name of the module and optionally the module slot.
  4. Click Save to add the new global module, or click Cancel to abort.
    • If you click Save, 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. Create a Custom Module

The following procedure describes how to create a custom module in order to make properties files and other resources available to all applications running on the JBoss EAP server.

Procedure 7.2. Create a Custom Module

  1. Create and populate the module/ directory structure.
    1. Create a directory structure under the EAP_HOME/module directory to contain the files and JARs. For example:
      $ cd EAP_HOME/modules/ 
      $ mkdir -p myorg-conf/main/properties
    2. Move the properties files to the EAP_HOME/modules/myorg-conf/main/properties/ directory you created in the previous step.
    3. Create a module.xml file in the EAP_HOME/modules/myorg-conf/main/ directory containing the following XML:
      <module xmlns="urn:jboss:module:1.1" name="myorg-conf">
          <resources>
              <resource-root path="properties"/>
          </resources>
      </module>
  2. Modify the ee subsystem in the server configuration file. You can use the Managemet CLI or you can manually edit the file.
    • Follow these steps to modify the server configuration file using the Management CLI.
      1. Start the server and connect to the Management CLI.
        • For Linux, enter the following at the command line:
           EAP_HOME/bin/jboss-cli.sh --connect
        • For Windows, enter the following at a command line:
          C:\>EAP_HOME\bin\jboss-cli.bat --connect
        You should see the following response:
        Connected to standalone controller at localhost:9999
      2. To create the myorg-conf <global-modules> element in the ee subsystem, type the following in the command line:
        /subsystem=ee:write-attribute(name=global-modules, value=[{"name"=>"myorg-conf","slot"=>"main"}])
        You should see the following result:
        {"outcome" => "success"}
    • Follow these steps if you prefer to manually edit the server configuration file.
      1. Stop the server and open the server configuration file in a text editor. If you are running a standalone server, this is the EAP_HOME/standalone/configuration/standalone.xml file, or the EAP_HOME/domain/configuration/domain.xml file if you are running a managed domain.
      2. Find the ee subsystem and add the global module for myorg-conf. The following is an example of the ee subsystem element, modified to include the myorg-conf element:

        Example 7.3. myorg-conf element

        <subsystem xmlns="urn:jboss:domain:ee:1.0" >            
            <global-modules>
                <module name="myorg-conf" slot="main" />            
            </global-modules>
        </subsystem>
  3. Assuming you copied a file named my.properties into the correct module location, you are now able to load properties files using code similar to the following:

    Example 7.4. Load properties file

    Thread.currentThread().getContextClassLoader().getResource("my.properties");

7.5. Define an External JBoss Module Directory

Summary
By default, JBoss EAP looks for modules in the EAP_HOME/modules/ directory. You can direct JBoss EAP to look in one or more external directories by defining a JBOSS_MODULEPATH environment variable or by setting the variable in the startup configuration file. This topic describes both methods.

Procedure 7.3. Set the JBOSS_MODULEPATH Environment Variable

  • To specify one or more external module directories, define the JBOSS_MODULEPATH environment variable.
    For Linux, use a colon to delimit a list of directories. For example:

    Example 7.5. JBOSS_MODULEPATH environment variable

    export JBOSS_MODULEPATH=EAP_HOME/modules/:/home/username/external/modules/directory/
    For Windows, use a semicolon to delimit a list of directories. For example:

    Example 7.6. JBOSS_MODULEPATH environment variable

    SET JBOSS_MODULEPATH=EAP_HOME\modules\;D:\JBoss-Modules\

Procedure 7.4. Set the JBOSS_MODULEPATH Variable in the Startup Configuration File

  • If you prefer not to set a global environment variable, you can set the JBOSS_MODULEPATH variable in the JBoss EAP startup configuration file. If you are running a standalone server, this is the EAP_HOME/bin/standalone.conf file. If the server is running in a managed domain, this is the EAP_HOME/bin/domain.conf file.
    The following is an example of the command that sets the JBOSS_MODULEPATH variable in the standalone.conf file:

    Example 7.7. standalone.conf entry

    JBOSS_MODULEPATH="EAP_HOME/modules/:/home/username/external/modules/directory/"

7.6. Reference

7.6.1. Included Modules

A table listing the JBoss EAP 6 included modules and whether they are supported can be found on the Customer Portal at https://access.redhat.com/articles/1122333.

7.6.2. Dynamic Module Naming

All deployments are loaded as modules by JBoss EAP 6 and named according to the following conventions.
  • 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.
  • 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.accounts.ear.reports.war.

Chapter 8. Jsvc

8.1. Introduction

8.1.1. About Jsvc

Jsvc is a set of libraries and applications which allow Java applications run on UNIX and UNIX-like platforms as a background service. It allows an application to perform operations as a privileged user, and then switch identity to a non-privileged user.
Jsvc uses three processes: a launcher process, a controller process and a controlled process. The controlled process is also the main Java thread. If the JVM crashes the controller process will restart it within 60 seconds. Jsvc is a daemon process and for JBoss EAP 6 it must be started by a privileged user.

Note

Jsvc is for use on Red Hat Enterprise Linux, Solaris and HP-UX only. For similar functionality on Microsoft Windows, see prunsrv.exe in the Native Utilities for Windows Server download available from the Red Hat Customer Portal.

8.1.2. Start and Stop JBoss EAP using Jsvc

The instructions for starting and stopping JBoss EAP using Jsvc vary, depending on which mode it is operating: standalone or domain. Be aware that if JBoss EAP is run in domain mode, Jsvc handles the process of the domain controller only. Whichever command you use to start JBoss EAP using Jsvc, it must be run by a privileged user.

Prerequisites

  • If JBoss EAP was installed using the Zip method:
    • Install the Native Utilities package for your operating system, available for download from the Red Hat Customer Portal. See Install Native Components and Native Utilities (Zip, Installer) in the Installation Guide.
    • Create the user account under which the JBoss EAP 6 instance will run. The account used to start and stop the server must have read and write access to the directory in which JBoss EAP was installed.
  • If JBoss EAP was installed using the RPM method, install the apache-commons-daemon-jsvc-eap6 package. See Install Native Components and Native Utilities (RPM Installation) in the Installation Guide.
The following commands are to start and stop JBoss EAP in either standalone or domain modes. Note that file locations are different depending on the method used to install Jsvc in JBoss EAP 6. Use the tables below to determine which files to use to resolve the variables in the commands.
Standalone Mode
The following instructions are to start or stop JBoss EAP in standalone mode.

Table 8.1. Jsvc File locations For Zip installations - Standalone Mode

File Reference in Instructions File Location
EAP-HOME
${eap-installation-location}/jboss-eap-${version}
JSVC-BIN
EAP_HOME/modules/system/layers/base/native/sbin/jsvc
JSVC-JAR
EAP_HOME/modules/system/layers/base/native/sbin/commons-daemon.jar
CONF-DIR
EAP_HOME/standalone/configuration
LOG-DIR
EAP_HOME/standalone/log

Table 8.2. Jsvc File Locations for RPM Installations - Standalone Mode

File Reference in Instructions File Location
EAP-HOME
/usr/share/jbossas
JSVC-BIN
/usr/bin/jsvc-eap6/jsvc
JSVC-JAR
EAP_HOME/modules/system/layers/base/native/sbin/commons-daemon.jar
CONF-DIR
/etc/jbossas/standalone
LOG-DIR
/var/log/jbossas/standalone

Start JBoss EAP in Standalone Mode

  • JSVC_BIN \
     -outfile LOG_DIR/jsvc.out.log   \
     -errfile LOG_DIR/jsvc.err.log   \
     -pidfile LOG_DIR/jsvc.pid  \
     -user jboss \
     -D[Standalone] -XX:+UseCompressedOops -Xms1303m \
     -Xmx1303m -XX:MaxPermSize=256m \
     -Djava.net.preferIPv4Stack=true 
     -Djboss.modules.system.pkgs=org.jboss.byteman \
     -Djava.awt.headless=true \
     -Dorg.jboss.boot.log.file=LOG_DIR/server.log \
     -Dlogging.configuration=file:CONF_DIR/logging.properties \
     -Djboss.modules.policy-permissions \
     -cp EAP_HOME/jboss-modules.jar:JSVC_JAR \
     -Djboss.home.dir=EAP_HOME \
     -Djboss.server.base.dir=EAP_HOME/standalone   \
     @org.jboss.modules.Main -start-method main \
     -mp EAP_HOME/modules \
     -jaxpmodule javax.xml.jaxp-provider \
     org.jboss.as.standalone

Stop JBoss EAP in Standalone Mode

  • JSVC_BIN \
     -stop \
     -outfile LOG_DIR/jsvc.out.log   \
     -errfile LOG_DIR/jsvc.err.log   \
     -pidfile LOG_DIR/jsvc.pid  \
     -user jboss \
     -D[Standalone] -XX:+UseCompressedOops -Xms1303m \
     -Xmx1303m -XX:MaxPermSize=256m \
     -Djava.net.preferIPv4Stack=true \
     -Djboss.modules.system.pkgs=org.jboss.byteman \
     -Djava.awt.headless=true \
     -Dorg.jboss.boot.log.file=LOG_DIR/server.log \
     -Dlogging.configuration=file:CONF_DIR/logging.properties \
     -Djboss.modules.policy-permissions \
     -cp EAP_HOME/jboss-modules.jar:JSVC_JAR \
     -Djboss.home.dir=EAP_HOME \
     -Djboss.server.base.dir=EAP_HOME/standalone   \
     @org.jboss.modules.Main -start-method main \
     -mp EAP_HOME/modules \
     -jaxpmodule javax.xml.jaxp-provider \
     org.jboss.as.standalone
Domain Mode
The following instructions are to start or stop JBoss EAP in domain mode. Note that for domain mode, you must replace the JAVA_HOME variable with the Java home directory.

Table 8.3. Jsvc File Locations for Zip Installations - Domain Mode

File Reference in Instructions File Location
EAP-HOME
${eap-installation-location}/jboss-eap-${version}
JSVC-BIN
EAP_HOME/modules/system/layers/base/native/sbin/jsvc
JSVC-JAR
EAP_HOME/modules/system/layers/base/native/sbin/commons-daemon.jar
CONF-DIR
EAP_HOME/domain/configuration
LOG-DIR
EAP_HOME/domain/log

Table 8.4. Jsvc File Locations for RPM Installations - Domain Mode

File Reference in Instructions File Location
EAP-HOME
/usr/share/jbossas
JSVC-BIN
/usr/bin/jsvc-eap6/jsvc
JSVC-JAR
EAP_HOME/modules/system/layers/base/native/sbin/commons-daemon.jar
CONF-DIR
/etc/jbossas/domain
LOG-DIR
/var/log/jbossas/domain

Start JBoss EAP in Domain Mode

  • JSVC_BIN \
     -outfile LOG_DIR/jsvc.out.log   \
     -errfile LOG_DIR/jsvc.err.log   \
     -pidfile LOG_DIR/jsvc.pid  \
     -user jboss \
     -nodetach -D"[Process Controller]" -server -Xms64m \
     -Xmx512m -XX:MaxPermSize=256m \
     -Djava.net.preferIPv4Stack=true  \
     -Djboss.modules.system.pkgs=org.jboss.byteman \
     -Djava.awt.headless=true  \
     -Dorg.jboss.boot.log.file=LOG_DIR/process-controller.log \
     -Dlogging.configuration=file:CONF_DIR/logging.properties \
     -Djboss.modules.policy-permissions \
     -cp "EAP_HOME/jboss-modules.jar:JSVC_JAR" \
     org.apache.commons.daemon.support.DaemonWrapper \
     -start org.jboss.modules.Main -start-method main \
     -mp EAP_HOME/modules org.jboss.as.process-controller \
     -jboss-home EAP_HOME -jvm $JAVA_HOME/bin/java \
     -mp EAP_HOME/modules -- \
     -Dorg.jboss.boot.log.file=LOG_DIR/host-controller.log \
     -Dlogging.configuration=file:CONF_DIR/logging.properties \
     -Djboss.modules.policy-permissions \
     -server -Xms64m -Xmx512m -XX:MaxPermSize=256m \
     -Djava.net.preferIPv4Stack=true \
     -Djboss.modules.system.pkgs=org.jboss.byteman \
     -Djava.awt.headless=true -- -default-jvm $JAVA_HOME/bin/java

Stop JBoss EAP in Domain Mode

  • JSVC_BIN \
     -stop \
     -outfile LOG_DIR/jsvc.out.log   \
     -errfile LOG_DIR/jsvc.err.log   \
     -pidfile LOG_DIR/jsvc.pid  \
     -user jboss \
     -nodetach -D"[Process Controller]" -server -Xms64m \
     -Xmx512m -XX:MaxPermSize=256m \
     -Djava.net.preferIPv4Stack=true  \
     -Djboss.modules.system.pkgs=org.jboss.byteman \
     -Djava.awt.headless=true  \
     -Dorg.jboss.boot.log.file=LOG_DIR/process-controller.log \
     -Dlogging.configuration=file:CONF_DIR/logging.properties \
     -Djboss.modules.policy-permissions \
     -cp "EAP_HOME/jboss-modules.jar:JSVC_JAR" \
     org.apache.commons.daemon.support.DaemonWrapper \
     -start org.jboss.modules.Main -start-method main \
     -mp EAP_HOME/modules org.jboss.as.process-controller \
     -jboss-home EAP_HOME -jvm $JAVA_HOME/bin/java \
     -mp EAP_HOME/modules -- \
     -Dorg.jboss.boot.log.file=LOG_DIR/host-controller.log \
     -Dlogging.configuration=file:CONF_DIR/logging.properties \
     -Djboss.modules.policy-permissions \
     -server -Xms64m -Xmx512m -XX:MaxPermSize=256m \
     -Djava.net.preferIPv4Stack=true \
     -Djboss.modules.system.pkgs=org.jboss.byteman \
     -Djava.awt.headless=true -- -default-jvm $JAVA_HOME/bin/java

Note

If JBoss EAP 6 is terminated abnormally, such as a JVM crash, Jsvc will automatically restart it. If JBoss EAP 6 is terminated correctly, Jsvc will also stop.

Chapter 9. Global Valves

9.1. About Valves

A Valve is a Java class that gets inserted into the request processing pipeline for an application. It is inserted in the pipeline before servlet filters. Valves can make changes to the request before passing it on or perform other processing such as authentication or even canceling the request.
Valves can be configured at the server level or at the application level. The only difference is in how they are configured and packaged.
  • Global Valves are configured at the server level and apply to all applications deployed to the server. Instructions to configure Global Valves are located in the Administration and Configuration Guide for JBoss EAP.
  • Valves configured at the application level are packaged with the application deployment and only affect the specific application. Instructions to configure Valves at the application level are located in the Development Guide for JBoss EAP.
Version 6.1.0 and later supports global valves.

9.2. About Global Valves

A Global Valve is a valve that is inserted into the request processing pipeline of all deployed applications. A valve is made global by being packaged and installed as a static module in JBoss EAP 6. Global valves are configured in the web subsystem.
Only version 6.1.0 and later supports global valves.
For instructions on how to configure Global Valves, see Section 9.5, “Configure a Global Valve”.

9.3. About Authenticator Valves

An authenticator valve is a valve that authenticates the credentials of a request. Such valve is a sub-class of org.apache.catalina.authenticator.AuthenticatorBase and overrides the authenticate(Request request, Response response, LoginConfig config) method.
This can be used to implement additional authentication schemes.

9.4. Install a Global Valve

Global valves must be packaged and installed as static modules in JBoss EAP 6. This task shows how to install the module.

Pre-requisities:

  • The valve must already be created and packaged in a JAR file.
  • A module.xml file must already be created for the module.
    Refer to Section 7.1.1, “Modules” for an example of module.xml file.

Procedure 9.1. Install a Global Module

  1. Create module installation directory

    A directory for the module to be installed in must be created in the modules directory of the application server.
    EAP_HOME/modules/system/layers/base/MODULENAME/main
    $ mkdir -P EAP_HOME/modules/system/layers/base/MODULENAME/main
  2. Copy files

    Copy the JAR and module.xml files to the directory created in step 1.
    $ cp MyValves.jar module.xml EAP_HOME/modules/system/layers/base/MODULENAME/main
The valve classes declared in the module are now available to be configured in the web subsystem.

9.5. Configure a Global Valve

Global valves are enabled and configured in the web subsystem. This is done using the JBoss CLI tool.

Procedure 9.2. Configure a Global Valve

  1. Enable the Valve

    Use the add operation to add a new valve entry.
    /subsystem=web/valve=VALVENAME:add(module="MODULENAME",class-name="CLASSNAME")
    You need to specify the following values:
    • VALVENAME, the name that is used to refer to this valve in application configuration.
    • MODULENAME, the module that contains the value being configured.
    • CLASSNAME, the classname of the specific valve in the module.
    For example:
    /subsystem=web/valve=clientlimiter:add(module="clientlimitermodule",class-name="org.jboss.samplevalves.RestrictedUserAgentsValve")
  2. Optionally: Specify Parameters

    If the valve has configuration parameters, specify these with the add-param operation.
    /subsystem=web/valve=VALVENAME:add-param(param-name="PARAMNAME", param-value="PARAMVALUE")
    You need to specify the following values:
    • VALVENAME, the name that is used to refer to this valve in application configuration.
    • PARAMNAME, the name of the parameter that is being configured for specific valve.
    • PARAMVALUE, the value of the specified parameter.
    For example:

    Example 9.1. Valve configuration

    /subsystem=web/valve=clientlimiter:add-param(
       param-name="restrictedUserAgents", 
       param-value="^.*MS Web Services Client Protocol.*$"
    )
The valve is now enabled and configured for all deployed applications.
Refer to Create a Custom Valve section of the Developement Guide for more information on how to create a custom valve.

Chapter 10. Application Deployment

10.1. About Application Deployment
10.2. Deploy with the Management Console
10.2.1. Manage Application Deployment in the Management Console
10.2.2. Enable a Deployed Application Using the Management Console
10.2.3. Disable a Deployed Application Using the Management Console
10.2.4. Undeploy an Application Using the Management Console
10.3. Deploy with the Management CLI
10.3.1. Manage Application Deployment in the Management CLI
10.3.2. Deploy an Application in a Standalone Server Using the Management CLI
10.3.3. Undeploy an Application in a Standalone Server Using the Management CLI
10.3.4. Deploy an Application in a Managed Domain Using the Management CLI
10.3.5. Undeploy an Application in a Managed Domain Using the Management CLI
10.4. Deploy with the HTTP API
10.4.1. Deploy an application using the HTTP API
10.5. Deploy with the Deployment Scanner
10.5.1. Manage Application Deployment in the Deployment Scanner
10.5.2. Deploy an Application to a Standalone Server Instance with the Deployment Scanner
10.5.3. Undeploy an Application from a Standalone Server Instance with the Deployment Scanner
10.5.4. Redeploy an Application to a Standalone Server Instance with the Deployment Scanner
10.5.5. Reference for Deployment Scanner Marker Files
10.5.6. Reference for Deployment Scanner Attributes
10.5.7. Configure the Deployment Scanner
10.5.8. Configure the Deployment Scanner with the Management CLI
10.5.9. Define a Custom Deployment Scanner
10.6. Deploy with Maven
10.6.1. Manage Application Deployment with Maven
10.6.2. Deploy an Application with Maven
10.6.3. Undeploy an Application with Maven
10.7. Control the order of Deployed Applications on JBoss EAP 6
10.8. Define a Custom Directory for Deployed Content
10.9. Deployment Descriptor Overrides
10.10. Rollout Plan
10.10.1. Rollout Plans
10.10.2. Operations with a Rollout Plan
10.10.3. Creating a Rollout Deployment Plan

10.1. About Application Deployment

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

Note

Before deploying any application, you can enable validation for deployment descriptors. This can be done by setting the org.jboss.metadata.parser.validate system property to true. This can be done in one of the two ways:
  • While starting the server.
    Example:
    • For domain mode:
      ./domain.sh -Dorg.jboss.metadata.parser.validate=true
    • For standalone mode:
      ./standalone.sh -Dorg.jboss.metadata.parser.validate=true
  • By defining it in the server configuration.
    For more information on configuring system properties using the Management CLI, refer Section 3.5.11, “Configure System Properties Using the Management CLI”

10.2. Deploy with the Management Console

10.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 enable, disable or delete applications from the content repository as required.

10.2.2. Enable a Deployed Application Using the Management Console

Procedure 10.1. Enable a Deployed Application using the Management Console

  • Select the Deployments tab from the top of the console.
    The deployment method for applications will differ depending on whether you are deploying to a standalone server instance or a managed domain.
    • Enable an application on a standalone server instance

      The Available Deployments table shows all available application deployments and their status.
      1. To enable an application in a standalone server instance, select the application, then click En/Disable.
        Available deployments

        Figure 10.1. Available deployments

      2. Click Confirm to confirm that the application will be enabled on the server instance.
        The confirmation dialogue box.

        Figure 10.2. Available deployments in a standalone server

    • Enable an application in a managed domain

      The Content Repository tab contains an Available Deployment Content table showing all available application deployments and their status.
      1. To enable an application in a Managed Domain, select the application to be deployed. Click Assign above the Available Deployment Content table.
        The Content Repository table for managed domains.

        Figure 10.3. Available deployments in a managed domain

      2. Check the boxes for each of the server groups that you want the application to be added to and click Save to finish.
      3. Select Server Groups tab to view the Server Groups table.
        The Server Groups table shows the status of deployed application.

        Figure 10.4. Confirmation of application deployment to server groups

      4. If your application is not already enabled, you can enable it now by clicking on View and then clicking on the En/Disable button. Click Confirm to confirm that the application will be enabled on the server instance.
Result
The application is enabled on the relevant server or server group.

10.2.3. Disable a Deployed Application Using the Management Console

Procedure 10.2. Disable a Deployed Application using the Management Console

  • Select the Deployment tab from the top of the console.
    The method used to disable an application will differ depending on whether you are deploying to a standalone server instance or a managed domain.
    • Disable a deployed application on a Standalone server instance

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

      Figure 10.5. Available deployments

      1. Select the application to be disabled. Click En/Disable to disable the selected application.
      2. Click Confirm to confirm that the application will be disabled on the server instance.
    • Disable a deployed application on a managed domain

      The Deployments screen contains a Content Repository tab. The Available Deployment Content table shows all available application deployments and their status.
      1. Select the Server Groups tab to view the server groups.
        The deployments for server groups in a managed domain.

        Figure 10.6. Server group deployments

      2. Select the name of the server group in the Server Group table to undeploy an application from. Click View to see the applications.
      3. Select the application and click En/Disable to disable the application for the selected server.
      4. Click Confirm to confirm that the application will be disabled on the server instance.
      5. Repeat as required for other server groups. The application status is confirmed for each server group in the Group Deployments table for that server group.
Result
The application is disabled from the relevant server or server group.

10.2.4. Undeploy an Application Using the Management Console

Procedure 10.3. Undeploy an Application Using the Management Console

  • Select the Deployments tab from the top of the console.
    The method used to undeploy an application will differ depending on whether you are undeploying from a standalone server instance or a managed domain.
    • Undeploy a deployed application from a Standalone server instance

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

      Figure 10.7. Available deployments

      1. Select the application to be undeployed. Click Remove to undeploy the selected application.
      2. Click Confirm to confirm that the application will be undeployed on the server instance.
    • Undeploy a deployed application from a managed domain

      The Deployments screen contains a Content Repository tab. The Available Deployment Content table shows all available application deployments and their status.
      1. Select the Server Groups tab to view the server groups and the status of their deployed applications.
        The deployments for server groups in a managed domain.

        Figure 10.8. Server group deployments

      2. Select the name of the server group in the Server Group table to undeploy an application from. Click View to see the applications.
      3. Select the application and click Remove to undeploy the application for the selected server.
      4. Click Confirm to confirm that the application will be undeployed on the server instance.
      5. Repeat as required for other server groups. The application status is confirmed for each server group in the Group Deployments table for that server group.
Result
The application is undeployed from the relevant server or server group. On a standalone instance the deployment content is also removed. On a managed domain, the deployment content remains in the content repository and is only undeployed from the server group.

10.3. Deploy with the Management CLI

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

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

Procedure 10.4. Deploy an Application in a Standalone Server

  • Run the deploy command

    From the Management CLI, enter the deploy command with the path to the application deployment.

    Example 10.1. The Deploy command

    [standalone@localhost:9999 /] deploy /path/to/test-application.war
    Note that a successful deploy does not produce any output to the CLI.
Result
The specified application is now deployed in the standalone server.

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

Procedure 10.5. Undeploy an Application in a Standalone Server

By default the undeploy command will undeploy and delete the deployment content from a standalone instance of JBoss EAP. To retain the deployment content, add the parameter --keep-content.
  • Run the undeploy command

    To undeploy the application and delete the deployment content, enter the Management CLI undeploy command with the filename of the application deployment.
    [standalone@localhost:9999 /] undeploy test-application.war
    To undeploy the application, but retain the deployment content, enter the Management CLI undeploy command with the filename of the application deployment and the parameter --keep-content.
    [standalone@localhost:9999 /] undeploy test-application.war --keep-content
Result
The specified application is now undeployed. Note that the undeploy command does not produce any output to the Management CLI if it is successful.

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

Procedure 10.6. Deploy an Application in a Managed Domain

  • 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
    • 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
    Note that a successful deploy does not produce any output to the CLI.
Result
The specified application is now deployed to a server group in your managed domain.

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

Procedure 10.7. Undeploy an Application in a Managed Domain

  • 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
    Note that a successful undeploy does not produce any output to the CLI.
Result
The specified application is now undeployed.

10.4. Deploy with the HTTP API

10.4.1. Deploy an application using the HTTP API

Summary
Applications can be deployed via the HTTP API using the following instructions.

Prerequisites

Procedure 10.8. Deploy an application using HTTP API

  • Use either the deploy or undeploy command relevant to your requirements.

    Example 10.2. Deploy and undeploy command

    Deploy
    ------------------------------
    curl --digest -L -D - http://<host>:<port>/management --header "Content-Type: application/json" -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "add", "address" : {"deployment" : "<runtime-name>"}, "content" : [{"url" : "file:<path-to-archive>}]},{"operation" : "deploy", "address" : {"deployment" : "<runtime-name>"}}],"json.pretty":1}' -u <user>:<pass>
    
    Example:
    -------
    curl --digest -L -D - http://localhost:9990/management --header "Content-Type: application/json" -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "add", "address" : {"deployment" : "example.war"}, "content" : [{"url" : "file:/home/$user/example.war"}]},{"operation" : "deploy", "address" : {"deployment" : "example.war"}}],"json.pretty":1}' -u user:password
    
    
    Undeploy
    ------------------------------
    curl --digest -L -D - http://<host>:<port>/management --header "Content-Type: application/json" -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "undeploy", "address" : {"deployment" : "<runtime-name>"}},{"operation" : "remove", "address" : {"deployment" : "<runtime-name>"}}],"json.pretty":1}' -u <user>:<pass>
    
    Example:
    -------
    curl --digest -L -D - http://localhost:9990/management --header "Content-Type: application/json" -d '{"operation" : "composite", "address" : [], "steps" : [{"operation" : "undeploy", "address" : {"deployment" : "example.war"}},{"operation" : "remove", "address" : {"deployment" : "example.war"}}],"json.pretty":1}' -u user:password
    

Note

To know more about programmatically generating the JSON requests, refer https://access.redhat.com/solutions/82463.

10.5. Deploy with the Deployment Scanner

10.5.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 behavior for a variety of application types.

10.5.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 10.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 10.9. Use the Deployment Scanner to Deploy Applications

  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

    There are two application deployment methods. You can choose between automatic and manual deployment scanner modes. Before starting either of the deployment methods, read Section 10.5.8, “Configure the Deployment Scanner with the Management CLI”.
    • Automatic deployment

      The deployment scanner picks up a change to the state of the folder and creates a marker file as defined in Section 10.5.8, “Configure the Deployment Scanner with the Management CLI”.
    • 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 10.3. 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 10.4. Deployment folder contents after deployment

example.war
example.war.deployed

10.5.3. Undeploy an Application from 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 10.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 10.10. Undeploy an Application using one of these Methods

  • 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

      Note

      Undeploying an exploded WAR file using this method is not valid. Only undeployment by removing the marker file is valid. Attempting to undeploy an exploded WAR file will result in a message like the following message being logged.
      WARN  [org.jboss.as.server.deployment.scanner] (DeploymentScanner-threads - 2) JBAS015006: The deployment scanner found that the content for exploded deployment EXAMPLE.war has been deleted, but auto-deploy/undeploy for exploded deployments is not enabled and the EXAMPLE.war.deployed marker file for this deployment has not been removed. As a result, the deployment is not being undeployed, but resources needed by the deployment may have been deleted and application errors may occur. Deleting the EXAMPLE.war.deployed marker file to trigger undeploy is recommended.
      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.

10.5.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 10.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 10.11. Redeploy an Application to a Standalone Server

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

10.5.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 10.6. 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 10.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.

10.5.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 10.5.8, “Configure the Deployment Scanner with the Management CLI”.

Table 10.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 600
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

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

10.5.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 behavior 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 10.5.6, “Reference for Deployment Scanner Attributes”.
The deployment scanner is a subsystem of JBoss EAP 6, and can be viewed in the standalone.xml.

Example 10.7. Excerpt from 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 10.12. Configure the Deployment Scanner

  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.

      Example 10.8. Sample read-resource output

      [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" => 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.4.5, “Obtain Help with the Management CLI”.

      Example 10.9. Sample ls -l output

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

10.5.9. Define a Custom Deployment Scanner

Summary
A new deployment scanner can be added using the Management Console or the Management CLI. This will define a new directory to scan for deployments. The default deployment scanner monitors EAP_HOME/standalone/deployments/. See Section 10.5.8, “Configure the Deployment Scanner with the Management CLI” for details on configuring an existing deployment scanner.

Procedure 10.13. Define a Custom Deployment Scanner with the Management CLI

  1. Add a deployment scanner using the Management CLI add operation:
    [standalone@localhost:9999 /] /subsystem=deployment-scanner/scanner=new-scanner:add(path=new_deployment_dir,relative-to=jboss.server.base.dir,scan-interval=5000)
    {"outcome" => "success"}

    Note

    The specified directory must already exist or this command will fail with an error.
  2. The new deployment scanner is now visible in the standalone.xml file and management interfaces.

    Example 10.10. Excerpt from standalone.xml

    <subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
    	<deployment-scanner path="deployments" relative-to="jboss.server.base.dir" scan-interval="5000"/>
    	<deployment-scanner name="new-scanner" path="new_deployment_dir" relative-to="jboss.server.base.dir" scan-interval="5000"/>
    </subsystem>
  3. The specified directory will now be scanned for deployments. See Section 10.5.2, “Deploy an Application to a Standalone Server Instance with the Deployment Scanner” for details on deploying an application with the deployment scanner.
Result
A new deployment scanner has been defined and is monitoring for deployments.

10.6. Deploy with Maven

10.6.1. Manage Application Deployment with Maven

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

10.6.2. Deploy an Application with Maven

Summary
This task shows a method for deploying applications with Maven. The example provided uses the jboss-helloworld.war application found in the JBoss EAP 6 Quickstarts 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 10.14. Deploy an application with Maven

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

    Example 10.11. Change into the helloworld application directory

    [localhost]$ cd /QUICKSTART_HOME/helloworld
    
  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. View the results.
    • The deployment can be confirmed by viewing the operation logs in the terminal window.

      Example 10.12. Maven confirmation for helloworld application

                              
      [INFO] ------------------------------------------------------------------------
      [INFO] BUILD SUCCESS
      [INFO] ------------------------------------------------------------------------
      [INFO] Total time: 32.629s
      [INFO] Finished at: Fri Mar 14 09:09:50 EDT 2014
      [INFO] Final Memory: 23M/204M
      [INFO] ------------------------------------------------------------------------
      
    • The deployment can also be confirmed in the status stream of the active application server instance.

      Example 10.13. Application server confirmation for helloworld application

      09:09:49,167 INFO  [org.jboss.as.repository] (management-handler-thread - 1) JBAS014900: Content added at location /home/username/EAP_HOME/standalone/data/content/32/4b4ef9a4bbe7206d3674a89807203a2092fc70/content
      09:09:49,175 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-7) JBAS015876: Starting deployment of "jboss-helloworld.war" (runtime-name: "jboss-helloworld.war")
      09:09:49,563 INFO  [org.jboss.weld.deployer] (MSC service thread 1-8) JBAS016002: Processing weld deployment jboss-helloworld.war
      09:09:49,611 INFO  [org.jboss.weld.deployer] (MSC service thread 1-1) JBAS016005: Starting Services for CDI deployment: jboss-helloworld.war
      09:09:49,680 INFO  [org.jboss.weld.Version] (MSC service thread 1-1) WELD-000900 1.1.17 (redhat)
      09:09:49,705 INFO  [org.jboss.weld.deployer] (MSC service thread 1-2) JBAS016008: Starting weld service for deployment jboss-helloworld.war
      09:09:50,080 INFO  [org.jboss.web] (ServerService Thread Pool -- 55) JBAS018210: Register web context: /jboss-helloworld
      09:09:50,425 INFO  [org.jboss.as.server] (management-handler-thread - 1) JBAS018559: Deployed "jboss-helloworld.war" (runtime-name : "jboss-helloworld.war")
Result
The application is deployed to the application server.

10.6.3. Undeploy an Application with Maven

Summary
This task shows a method for undeploying applications with Maven. The example provided uses the jboss-helloworld.war application found in the JBoss EAP 6 Quickstarts 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 10.15. Undeploy an Application with Maven

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

    Example 10.14. Change into the helloworld application directory

    [localhost]$ cd /QUICKSTART_HOME/helloworld
    
  2. Run the Maven undeploy command to undeploy the application.
    [localhost]$ mvn jboss-as:undeploy
  3. View the results.
    • The undeployment can be confirmed by viewing the operation logs in the terminal window.

      Example 10.15. Maven confirmation for undeploy of helloworld application

      [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] ------------------------------------------------------------------------
    • The undeployment can also be confirmed in the status stream of the active application server instance.

      Example 10.16. Application server confirmation for undeploy of helloworld application

      09:51:40,512 INFO  [org.jboss.web] (ServerService Thread Pool -- 69) JBAS018224: Unregister web context: /jboss-helloworld
      09:51:40,522 INFO  [org.jboss.weld.deployer] (MSC service thread 1-3) JBAS016009: Stopping weld service for deployment jboss-helloworld.war
      09:51:40,536 INFO  [org.jboss.as.server.deployment] (MSC service thread 1-1) JBAS015877: Stopped deployment jboss-helloworld.war (runtime-name: jboss-helloworld.war) in 27ms
      09:51:40,621 INFO  [org.jboss.as.repository] (management-handler-thread - 10) JBAS014901: Content removed from location /home/username/EAP_HOME/jboss-eap-6.4/standalone/data/content/44/e1f3c55c84b777b0fc201d69451223c09c9da5/content
      09:51:40,621 INFO  [org.jboss.as.server] (management-handler-thread - 10) JBAS018558: Undeployed "jboss-helloworld.war" (runtime-name: "jboss-helloworld.war")
      
Result
The application is undeployed from the application server.

10.7. Control the order of Deployed Applications on JBoss EAP 6

JBoss EAP 6 offers fine grained control over the order of deployment of applications when the server is started. Strict order of deployment of applications present in multiple ear files can be enabled along with persistence of the order after a restart.

Procedure 10.16. Control the order of deployment in EAP 6.0

  1. Create CLI scripts that will deploy and undeploy the applications in sequential order when the server is started/stopped.
  2. CLI also supports the concept of batch mode which allows you to group commands and operations and execute them together as an atomic unit. If at least one of the commands or operations fails, all the other successfully executed commands and operations in the batch are rolled back.

Procedure 10.17. Control the order of deployment in EAP 6.1 and later

From EAP 6.1 onward, Inter Deployment Dependencies allows you to declare dependencies between top level deployments.
  1. Create (if it doesn't exist) a jboss-all.xml file in the app.ear/META-INF folder, where app.ear is the application archive that depends on another application archive to be deployed before it is.
  2. Make a jboss-deployment-dependencies entry in this file as shown below. Note that in the listing below, framework.ear is the dependency application archive that should be deployed before app.ear application archive is.
    <jboss umlns="urn:jboss:1.0">
      <jboss-deployment-dependencies xmlns="urn:jboss:deployment-dependencies:1.0">
        <dependency name="framework.ear" />
      </jboss-deployment-dependencies>
    </jboss>

10.8. Define a Custom Directory for Deployed Content

JBoss EAP provides the option to define the location that the server will use for storing deployed content.
Define a Custom Directory for Deployed Content in Standalone Mode
By default, deployed content in Standalone Mode is stored in the EAP_HOME/standalone/data/content directory.
  • This location can be changed by passing in the -Djboss.server.deploy.dir argument when starting the server:
    ./standalone.sh -Djboss.server.deploy.dir=/path/to/new_deployed_content
  • The chosen location should be unique among JBoss EAP instances.

Note

jboss.server.deploy.dir specifies the directory used for storing content that has been deployed via the Management Console or Management CLI. For defining a custom deployments directory to be monitored by the deployment scanner, see Section 10.5.9, “Define a Custom Deployment Scanner”.
Define a Custom Directory for Deployed Content in Domain Mode
By default, deployed content in Domain Mode is stored in the EAP_HOME/domain/data/content directory.
  • This location can be changed by passing in the -Djboss.domain.deployment.dir argument when starting the domain:
    ./domain.sh -Djboss.domain.deployment.dir=/path/to/new_deployed_content
  • The chosen location should be unique among JBoss EAP instances.

10.9. Deployment Descriptor Overrides

From JBoss EAP 6.1 onward you can override deployment descriptors, JARs, classes, JSP pages, and other files at runtime. A deployment overlay represents a ruleset of files that must be overridden in the archive. It also provides links to the new files that must be used instead of the overridden ones. If the file being overridden is not present in the deployment archive, it will be added back to the deployment.

Procedure 10.18. Override the deployment descriptor using the Management CLI

The following steps assume that you already have a deployed application called app.war and you wish to override its WEB-INF/web.xml file with another web.xml file located in /home/user/web.xml.
  1. Add a deployment overlay and add content to it. You can achieve this in the following two ways:
    • Using DMR tree

      1. /deployment-overlay=myoverlay:add
      2. /deployment-overlay=myoverlay/content=WEB-INF\/web.xml:add(content={url=file:///home/user/web.xml})
        You can also add more content rules using the second statement.
    • Using convenience methods

      deployment-overlay add --name=myoverlay --content=WEB-INF/web.xml=/home/user/web.xml
  2. Link the overlay to a deployment archive. You can achieve this in the following two ways:
    • Using DMR tree

      /deployment-overlay=myoverlay/deployment=app.war:add
    • Using convenience methods

      deployment-overlay link --name=myoverlay --deployments=app.war
      To specify multiple archive names, separate them by commas.
    Note that the deployment archive name need not exist on the server. You are specifying the name, but not yet linking it to an actual deployment.
  3. Redeploy the application

    /deployment=app.war:redeploy

10.10. Rollout Plan

10.10.1. Rollout Plans

Operations targeted at domain or host level resources can potentially impact multiple servers. Such operations can include a roll out plan detailing the sequence in which the operation would be applied to the servers, as well as the policies for detailing whether the operation could be reverted if it fails to execute successfully on some servers.

Example 10.17. CLI format of a rollout plan

rollout (id=plan_id | server_group_list) [rollback-across-groups]

server_group_list := server_group [ (sequence_separator | concurrent_separator) server_group ]
sequence_separator := ','
concurrent_separator := '^'
server_group := server_group_name [group_policy_list]
group_policy_list := '(' policy_property_name=policy_property_value (, policy_property_name=policy_property_value)* ')'
policy_property_name := 'rolling-to-servers' | 'max-failed-servers' | 'max-failure-percentage'
The value of policy_property_value depends on the property. It can be a boolean, an integer, etc.
Rollout plans can potentially be long and complex. There is a possibility, though, to store them as a part of the domain management model and then later be referenced from commands and operations using their name (or ID in the definition above). Stored rollout plans are managed using the rollout-plan command.

Example 10.18. Rollout plan managed with the rollout-plan command

rollout-plan add --name=my-plan --content={rollout main-server-group^other-server-group}
:write-attribute(name=my-attr,value=my-value){rollout id=my-plan}	

Example 10.19. Using a stored rollout plan

rollout-plan add --name=my-plan --content={rollout main-server-group^other-server-group}
:write-attribute(name=my-attr,value=my-value){rollout id=my-plan}

10.10.2. Operations with a Rollout Plan

The structure is of rollout-plan within an operation is as follows:
{
"operation" => "write-core-threads",
    "address" => [
        ("profile" => "production"),
        ("subsystem" => "threads"),
        ("bounded-queue-thread-pool" => "pool1")
    ],
    "count" => 0,
    "per-cpu" => 20,
    "operation-headers" => {
        "rollout-plan" => {
            "in-series" => [
                {
                    "concurrent-groups" => {
                        "groupA" => {
                            "rolling-to-servers" => true,
                            "max-failure-percentage" => 20
                        },
                        "groupB" => undefined
                    }
                },
                {
                   "server-group" => {
                        "groupC" => {
                            "rolling-to-servers" => false,
                            "max-failed-servers" => 1
                        }
                    }
                },
                {
                    "concurrent-groups" => {
                        "groupD" => {
                            "rolling-to-servers" => true,
                            "max-failure-percentage" => 20
                        },
                        "groupE" => undefined
                    }
                }
            ],
            "rollback-across-groups" => true
        }
    }
}
The rollout-plan is nested within the operation-headers structure. The root node of the structure allows two children:
  • in-series - A list of steps that are to be performed in series, with each step reaching completion before the next step is executed. Each step involves the application of the operation to the servers in one or more server groups. See below for details on each element in the list.
  • rollback-across-groups - A boolean that indicates whether the need to rollback the operation on all the servers in one server group triggers a rollback across all the server groups. This is an optional setting, and defaults to false.
Each element in the list under the in-series node must have one or the other of the following structures:
  • concurrent-groups - A map of server group names to policies controlling how the operation should be applied to that server group. For each server group in the map, the operation may be applied concurrently. See below for details on the per-server-group policy configuration.
  • server-group - A single key/value mapping of a server group name to a policy controlling how the operation should be applied to that server group. See below for details on the policy configuration. (Note: there is no difference in plan execution between this and a "concurrent-groups" map with a single entry.)
The policy controlling how the operation is applied to the servers within a server group has the following elements, each of which is optional:
  • rolling-to-servers - A boolean which if set to true, the operation will be applied to each server in the group in series. If false or not specified, the operation will be applied to the servers in the group concurrently.
  • max-failed-servers - An integer which takes the maximum number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is zero; i.e. failure on any server triggers rollback across the group.
  • max-failure-percentage - An integer between 0 and 100 which takes the maximum percentage of the total number of servers in the group that can fail to apply the operation before it should be reverted on all servers in the group. The default value if not specified is zero; i.e. failure on any server triggers rollback across the group.
If both max-failed-servers and max-failure-percentage are set to non-zero values, max-failure-percentage takes precedence.
Looking at the (contrived) example above, application of the operation to the servers in the domain would be done in 3 phases. If the policy for any server group triggers a rollback of the operation across the server group, all other server groups will be rolled back as well. The 3 phases are:
  1. Server groups groupA and groupB will have the operation applied concurrently. The operation will be applied to the servers in groupA in series, while all servers in groupB will handle the operation concurrently. If more than 20% of the servers in groupA fail to apply the operation, it will be rolled back across that group. If any servers in groupB fail to apply the operation it will be rolled back across that group.
  2. Once all servers in groupA and groupB are complete, the operation will be applied to the servers in groupC. Those servers will handle the operation concurrently. If more than one server in groupC fails to apply the operation it will be rolled back across that group.
  3. Once all servers in groupC are complete, server groups groupD and groupE will have the operation applied concurrently. The operation will be applied to the servers in groupD in series, while all servers in groupE will handle the operation concurrently. If more than 20% of the servers in groupD fail to apply the operation, it will be rolled back across that group. If any servers in groupE fail to apply the operation it will be rolled back across that group.
Default Rollout Plan
All operations that impact multiple servers will be executed with a rollout plan. However, actually specifying the rollout plan in the operation request is not required. If no rollout-plan is specified, a default plan will be generated. The plan will have the following characteristics:
  • There will only be a single high level phase. All server groups affected by the operation will have the operation applied concurrently.
  • Within each server group, the operation will be applied to all servers concurrently.
  • Failure on any server in a server group will cause rollback across the group.
  • Failure of any server group will result in rollback of all other server groups.

10.10.3. Creating a Rollout Deployment Plan

How to create a roll out deployment plan to deploy applications in a clustered domain in JBoss EAP 6
  1. Create a rollout deployment plan using CLI with rolling-to-servers=true. The package will be deployed to each server in the server group in a serial manner.
    An example CLI deployment plan for serial deployment is provided below:
    deploy ClusterWebApp.war --name=ClusterWebApp.war --runtime-name=ClusterWebApp.war --server-groups=ha-server-group --headers={rollout ha-server-group(rolling-to-servers=true)}
    
  2. To apply a rollout plan to all the server-groups, you need to mention the names of each server-group in master host:
    deploy /NotBackedUp/PREVIOUS/ALLWAR/ClusterWebApp.war --name=ClusterWebApp.war --runtime-name=ClusterWebApp.war --server-groups=main-server-group,other-server-group --headers={rollout main-server-group(rolling-to-servers=true),other-server-group(rolling-to-servers=true)}
    

Chapter 11. Subsystem Configuration

11.1. Subsystem Configuration Overview

Introduction
JBoss EAP 6 uses a simplified configuration, with one configuration file per domain or per standalone server. In domain mode, a separate file exists for each host controller as well. Changes to the configuration persist automatically, so XML configuration file should not be edited manually. The configuration is scanned and overwritten automatically by the Management API. The command-line based Management CLI and web-based Management Console allow you to configure each aspect of JBoss EAP 6.
JBoss EAP 6 is built on the concept of modular class loading. Each API or service provided by the Platform is implemented as a module, which is loaded and unloaded on demand. Most modules include a configurable element called a subsystem. Subsystem configuration information is stored in the unified configuration file EAP_HOME/domain/configuration/domain.xml for a managed domain or EAP_HOME/standalone/configuration/standalone.xml for a standalone server. Many of the subsystems include configuration details that were configured via deployment descriptors in previous versions of JBoss EAP.
Subsystem Configuration Schemas
Each subsystem's configuration is defined in an XML schema. The configuration schemas are located in the EAP_HOME/docs/schema/ directory of your installation.

Chapter 12. The Logging Subsystem

12.1. Introduction
12.1.1. Overview of Logging
12.1.2. Application Logging Frameworks Supported By JBoss LogManager
12.1.3. Bootup Logging
12.1.4. View Bootup Errors
12.1.5. About Garbage Collection Logging
12.1.6. Implicit Logging API Dependencies
12.1.7. Default Log File Locations
12.1.8. Filter Expressions for Logging
12.1.9. About Log Levels
12.1.10. Supported Log Levels
12.1.11. About Log Categories
12.1.12. About the Root Logger
12.1.13. About Log Handlers
12.1.14. Types of Log Handlers
12.1.15. About Log Formatters
12.1.16. Log Formatter Syntax
12.2. Configure Logging in the Management Console
12.3. Logging Configuration in the CLI
12.3.1. Configure the Root Logger with the CLI
12.3.2. Configure a Log Category in the CLI
12.3.3. Configure a Console Log Handler in the CLI
12.3.4. Configure a File Log Handler in the CLI
12.3.5. Configure a Periodic Log Handler in the CLI
12.3.6. Configure a Size Log Handler in the CLI
12.3.7. Configure a Periodic Size Rotating Log Handler in the CLI
12.3.8. Configure a Async Log Handler in the CLI
12.3.9. Configure a Custom Handler in the CLI
12.3.10. Configure a Syslog Handler in the CLI
12.3.11. Configure a Custom Log Formatter in the CLI
12.4. Per-deployment Logging
12.4.1. About Per-deployment Logging
12.4.2. Disable Per-deployment Logging
12.5. Logging Profiles
12.5.1. About Logging Profiles
12.5.2. Create a new Logging Profile using the CLI
12.5.3. Configuring a Logging Profile using the CLI
12.5.4. Specify a Logging Profile in an Application
12.5.5. Example Logging Profile Configuration
12.6. Logging Configuration Properties
12.6.1. Root Logger Properties
12.6.2. Log Category Properties
12.6.3. Console Log Handler Properties
12.6.4. File Log Handler Properties
12.6.5. Periodic Log Handler Properties
12.6.6. Size Log Handler Properties
12.6.7. Periodic Size Rotating Log Handler Properties
12.6.8. Async Log Handler Properties
12.7. Sample XML Configuration for Logging
12.7.1. Sample XML Configuration for the Root Logger
12.7.2. Sample XML Configuration for a Log Category
12.7.3. Sample XML Configuration for a Console Log Handler
12.7.4. Sample XML Configuration for a File Log Handler
12.7.5. Sample XML Configuration for a Periodic Log Handler
12.7.6. Sample XML Configuration for a Size Log Handler
12.7.7. Sample XML Configuration for a Periodic Size Rotating Log Handler
12.7.8. Sample XML Configuration for a Async Log Handler

12.1. Introduction

12.1.1. Overview of Logging

JBoss EAP 6 provides highly configurable logging facilities for both its own internal use and for use by deployed applications. The logging subsystem is based on JBoss LogManager and it supports several third party application logging frameworks in addition to JBoss Logging.
The logging subsystem is configured using a system of log categories and log handlers. Log categories define what messages to capture, and log handlers define how to deal with those messages (write to disk, send to console etc).
Logging Profiles allow uniquely named sets of logging configuration to be created and assigned to applications independent of any other logging configuration. The configuration of logging profiles is almost identical to the main logging subsystem.

12.1.2. Application Logging Frameworks Supported By JBoss LogManager

JBoss LogManager supports the following logging frameworks:
JBoss LogManager supports the following APIs:
  • java.util.logging
  • JBoss Logging
  • Log4j
  • SLF4J
  • commons-logging
JBoss LogManager also supports the following SPIs:
  • java.util.logging Handler
  • Log4j Appender

Note

If you are using the Log4j API and a Log4J Appender, then Objects will be converted to string before being passed.

12.1.3. Bootup Logging

During bootup JBoss EAP outputs log entries about the Java environment and the startup of each service. The log can be useful when troubleshooting. By default all log entries are written to the file server.log, the location of which depends on the runtime mode.
Standalone mode
EAP_HOME/standalone/log/server.log
Domain mode
EAP_HOME/domain/servers/SERVER_NAME/log/server.log
The configuration of bootup logging is specified in the configuration file logging.properties, the location of which depends on the runtime mode.
Standalone mode
EAP_HOME/standalone/configuration/logging.properties
Domain mode
In domain mode there is a logging.properties file for the domain controller and each server.
Domain controller: EAP_HOME/domain/configuration/logging.properties
Server: EAP_HOME/domain/servers/SERVER_NAME/data/logging.properties
The configuration file logging.properties is active until the logging subsystem is started and takes over.

Warning

It is recommended that you do not directly edit the logging.properties file unless you know of a specific use case that requires you to do so. Before doing so, it is recommended that you raise a Support Case.
Changes made manually to the logging.properties file are overwritten on startup.

12.1.4. View Bootup Errors

When troubleshooting JBoss EAP, checking for errors which occurred during bootup should be one of the first steps taken. There are two methods of viewing bootup errors, each with its advantages. Each method results in a list of any errors which occurred during bootup. Use the information provided to diagnose and resolve their causes. Contact Red Hat Customer Support for assistance in troubleshooting.
  • Examine the server.log log file.
    This method allows you to see each error message together with possibly related messages, allowing you to get more information about why an error might have occurred. It also allows you to see error messages in plain text format.
  • From JBoss EAP 6.4, use the Management CLI command read-boot-errors.
    This method does not require access to the server's file system, which is useful for anyone responsible for monitoring for errors who does not have file system access. Since it is a Management CLI command, it can be used in a script. For example, you could write a script which starts multiple JBoss EAP instances, then checks for errors which occurred on bootup.

Procedure 12.1.  Examine server.log for Errors

  1. Open the file server.log in a file viewer.
  2. Navigate to the end of the file.
  3. Search backward for the message identifier JBAS015899, which marks the start of the latest bootup sequence.
  4. Search the log from that point onward for instances of ERROR. Each instance will include a description of the error and list the modules involved.

Example 12.1.  Error Description from server.log

The following is an example error description from the server.log log file.
13:23:14,281 ERROR [org.apache.coyote.http11.Http11Protocol] (MSC service thread 1-4) JBWEB003043: Error initializing endpoint: java.net.BindException: Address already in use /127.0.0.1:8080

Procedure 12.2. List Bootup Errors via the Management CLI

  • Run the following Management CLI command.
    /core-service=management:read-boot-errors
    Any errors which occurred during bootup will be listed.
    The timestamp of each error uses the Java method currentTimeMillis(), which is the difference, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC(coordinated universal time).

Example 12.2.  Output from read-boot-errors Command

{
"outcome" => "success",
"result" => [{
    "failed-operation" => {
        "operation" => "add",
        "address" => [
            ("subsystem" => "web"),
            ("connector" => "http")
        ]
    },
    "failure-timestamp" => 1417560953245L,
    "failure-description" => "{\"JBAS014671: Failed services\" => {\"jboss.web.connector.http\" => \"org.jboss.msc.service.StartException in service jboss.web.connector.http: JBAS018007: Error starting web connector
Caused by: LifecycleException:  JBWEB000023: Protocol handler initialization failed\"}}",
    "failed-services" => {"jboss.web.connector.http" => "org.jboss.msc.service.StartException in service jboss.web.connector.http: JBAS018007: Error starting web connector
Caused by: LifecycleException:  JBWEB000023: Protocol handler initialization failed"}
}]
}

12.1.5. About Garbage Collection Logging

Garbage collection logging logs all garbage collection activity to plain text log files. These log files can be useful for diagnostic purposes. From JBoss EAP 6 garbage collection logging is enabled by default for standalone mode on all supported configurations except IBM Java development kit.
Logging is output to the file EAP_HOME/standalone/log/gc.log.digit. Log rotation has been enabled, with the number of log files limited to five and each file limited to a maximum size of three MiB.

12.1.6. Implicit Logging API Dependencies

The JBoss EAP 6 logging subsystem has the add-logging-api-dependencies attribute that controls whether the container adds implicit logging API dependencies to deployments. By default this attribute is set to true, which means that all implicit logging API dependencies are added to deployments. If set to false, implicit logging API dependencies will not be added.
The add-logging-api-dependencies attribute can be configured using the Management CLI. For example:
/subsystem=logging:write-attribute(name=add-logging-api-dependencies, value=false)

12.1.7. Default Log File Locations

These are the log files that get created for the default logging configurations. The default configuration writes the server log files using periodic log handlers

Table 12.1. Default Log File for a standalone server

Log File Description
EAP_HOME/standalone/log/server.log
Server Log. Contains all server log messages, including server startup messages.
EAP_HOME/standalone/log/gc.log
Garbage collection log. Contains details of all garbage collection.

Table 12.2. Default Log Files for a managed domain

Log File Description
EAP_HOME/domain/log/host-controller.log
Host Controller boot log. Contains log messages related to the startup of the host controller.
EAP_HOME/domain/log/process-controller.log
Process controller boot log. Contains log messages related to the startup of the process controller.
EAP_HOME/domain/servers/SERVERNAME/log/server.log
The server log for the named server. Contains all log messages for that server, including server startup messages.

12.1.8. Filter Expressions for Logging

Filter expressions are used to record log messages based on various criterion. Filter checking is always done on a raw unformatted message. You can include a filter for a logger or handler, the logger filter takes precedence over the filter put on a handler.

Note

A filter-spec specified for the root logger is not inherited by other loggers. Instead a filter-spec must be specified per handler.

Table 12.3. Filter Expressions for Logging

Filter Type
expression
Description Parameters
Accept
accept
Accept all log messages
accept
Deny
deny
Deny all log messages
deny
Not
not[filter expression]
Returns the inverted value of the filter expression
Takes single filter expression as a parameter
not(match("JBAS"))
All
all[filter expression]
Returns concatenated value from multiple filter expressions.
Takes multiple filter expressions delimited by commas
all(match("JBAS"),match("WELD"))
Any
any[filter expression]
Returns one value from multiple filter expressions.
Takes multiple filter expressions delimited by commas
any(match("JBAS"),match("WELD"))
Level Change
levelChange[level]
Modifies the log record with the specified level
Takes single string-based level as an argument
levelChange("WARN")
Levels
levels[levels]
Filters log messages with a level listed in the list of levels
Takes multiple string-based levels delimited by commas as argument
levels("DEBUG","INFO","WARN","ERROR")
Level Range
levelRange[minLevel,maxLevel]
Filters log messages within the specified level range.
The filter expression uses [ to indicate a minimum inclusive level and a ] to indicate a maximum inclusive level. Alternatively, one can use ( or ) respectively to indicate exclusive. The first argument for the expression is the minimum level allowed, the second argument is the maximum level allowed.
Examples are shown below.
  • levelRange("DEBUG","ERROR")
    Minimum level must be greater than DEBUG and the maximum level must be less than ERROR.
  • levelRange["DEBUG","ERROR")
    Minimum level must be greater than or equal to DEBUG and the maximum level must be less than ERROR.
  • levelRange["INFO","ERROR"]
    Minimum level must be greater than or equal to INFO and the maximum level must be less than or equal to ERROR.
Match (match["pattern"]) A regular-expression based filter. The unformatted message is used against the pattern specified in the expression.
Takes a regular expression as argument
match("JBAS\d+")
Substitute (substitute["pattern","replacement value"]) A filter which replaces the first match to the pattern with the replacement value
The first argument for the expression is the pattern the second argument is the replacement text
substitute("JBAS","EAP")
Substitute All (substituteAll["pattern","replacement value"]) A filter which replaces all matches of the pattern with the replacement value
The first argument for the expression is the pattern the second argument is the replacement text
substituteAll("JBAS","EAP")

Note

Escape the comma and quotation marks in the value (by preceding them with the '\' operator) and wrap the entire expression in quotation marks, so that the value is correctly interpreted to be a string. Otherwise, it would be parsed as a list. An example of the correct format would be:
[standalone@localhost:9999 /] /subsystem=logging/console-handler=CONSOLE:write-attribute(name=filter-spec, value="substituteAll(\"JBAS\"\,\"SABJ\")")

12.1.9. About Log Levels

Log levels are an ordered set of enumerated values that indicate the nature and severity of a log message. The level of a given log message is specified by the developer using the appropriate methods of their chosen logging framework to send the message.
JBoss EAP 6 supports all the log levels used by the supported application logging frameworks. The most commonly used six log levels are (in order of lowest to highest): TRACE, DEBUG, INFO, WARN, ERROR and FATAL.
Log levels are used by log categories and handlers to limit the messages they are responsible for. Each log level has an assigned numeric value which indicates its order relative to other log levels. Log categories and handlers are assigned a log level and they only process log messages of that level or higher. For example a log handler with the level of WARN will only record messages of the levels WARN, ERROR and FATAL.

12.1.10. Supported Log Levels

Table 12.4. Supported Log Levels

Log Level Value Description
FINEST 300
-
FINER 400
-
TRACE 400
Use for messages that provide detailed information about the running state of an application. Log messages of TRACE are usually only captured when debugging an application.
DEBUG 500
Use for messages that indicate the progress individual requests or activities of an application. Log messages of DEBUG are usually only captured when debugging an application.
FINE 500
-
CONFIG 700
-
INFO 800
Use for messages that indicate the overall progress of the application. Often used for application startup, shutdown and other major lifecycle events.
WARN 900
Use to indicate a situation that is not in error but is not considered ideal. May indicate circumstances that may lead to errors in the future.
WARNING 900
-
ERROR 1000
Use to indicate an error that has occurred that could prevent the current activity or request from completing but will not prevent the application from running.
SEVERE 1000
-
FATAL 1100
Use to indicate events that could cause critical service failure and application shutdown and possibly cause JBoss EAP 6 to shutdown.

12.1.11. About Log Categories

Log categories define a set of log messages to capture and one or more log handlers which will process the messages.
The log messages to capture are defined by their Java package of origin and log level. Messages from classes in that package and of that log level or lower are captured by the log category and sent to the specified log handlers.
Log categories can optionally use the log handlers of the root logger instead of their own handlers.

12.1.12. About the Root Logger

The root logger captures all log messages sent to the server (of a specified level) that are not captured by a log category. These messages are then sent to one or more log handlers.
By default the root logger is configured to use a console and a periodic log handler. The periodic log handler is configured to write to the file server.log. This file is sometimes referred to as the server log.

12.1.13. About Log Handlers

Log handlers define how captured log messages are recorded. The available log handlers are: Console, File, Periodic, Size, Async, syslog, Periodic Size and Custom.

Note

A log handler must be added to at least one logger to be active.

12.1.14. Types of Log Handlers

Console
Console log handlers write log messages to either the host operating system's standard out (stdout) or standard error (stderr) stream. These messages are displayed when JBoss EAP 6 is run from a command line prompt. The messages from a Console log handler are not saved unless the operating system is configured to capture the standard out or standard error stream.
File
File log handlers write log messages to a specified file.
Periodic
Periodic log handlers write log messages to a named file until a specified period of time has elapsed. Once the time period has passed then the file is renamed by appending the specified timestamp and the handler continues to write into a newly created log file with the original name.
Size
Size log handlers write log messages to a named file until the file reaches a specified size. When the file reaches a specified size, it is renamed with a numeric suffix and the handler continues to write into a newly created log file with the original name. Each size log handler must specify the maximum number of files to be kept in this fashion.
Periodic Size
Available from JBoss EAP 6.4. This is a combination of the Periodic and Size handlers and supports their combined attributes.
Once the current log file reaches the specified size, or the specified time period has passed, the file is renamed and the handler continues to write to a newly created log file with the original name.
Async
Async log handlers are wrapper log handlers that provide asynchronous behavior for one or more other log handlers. These are useful for log handlers that may have high latency or other performance problems such as writing a log file to a network file system.
Custom
Custom log handlers enable to you to configure new types of log handlers that have been implemented. A custom handler must be implemented as a Java class that extends java.util.logging.Handler and be contained in a module.
syslog
Syslog handlers can be used to send messages to a remote logging server. This allows multiple applications to send their log messages to the same server, where they can all be parsed together.

12.1.15. About Log Formatters

A log formatter is the configuration property of a log handler that defines the appearance of log messages from that handler. It is a string that uses a syntax based on java.util.Formatter class.
For example the log formatter string from the default configuration, %d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n , creates log messages that look like:
15:53:26,546 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015951: Admin console listening on http://127.0.0.1:9990

12.1.16. Log Formatter Syntax

Table 12.5. Log Formatter Syntax

Symbol Description
%c The category of the logging event
%p The level of the log entry (info/debug/etc)
%P The localized level of the log entry
%d The current date/time (yyyy-MM-dd HH:mm:ss,SSS form)
%r The relative time (milliseconds since the log was initialized)
%z The time zone
%k A log resource key (used for localization of log messages)
%m The log message (including exception trace)
%s The simple log message (no exception trace)
%e The exception stack trace (no extended module information)
%E The exception stack trace (with extended module information)
%t The name of the current thread
%n A newline character
%C The class of the code calling the log method (slow)
%F The filename of the class calling the log method (slow)
%l The source location of the code calling the log method (slow)
%L The line number of the code calling the log method (slow)
%M The method of the code calling the log method (slow)
%x The Nested Diagnostic Context
%X The Message Diagnostic Context
%% A literal percent character (escaping)

12.2. Configure Logging in the Management Console

The management console provides a graphical user interface for the configuration of the root logger, log handlers, and log categories. See Section 3.3.1, “Management Console” for more information about the Management Console.
To access logging configuration, follow the steps below.

Procedure 12.3. Access Logging configuration

  1. Log in to the Management Console
  2. Navigate to the logging subsystem configuration. This step varies between servers running as standalone servers and servers running in a managed domain.
    • Standalone Server

      Click on Configuration, expand Core in the Subsystems menu, and then click Logging.
    • Managed Domain

      Click on Configuration, select the profile to edit from the drop-down menu. Expand Core in the Subsystems menu, and then click Logging.
The tasks you can perform to configure the root logger are:
  • Edit the log level.
  • Add and remove log handlers.
The tasks you can perform to configure log categories are:
  • Add and remove log categories.
  • Edit log category properties.
  • Add and remove log handlers from a category.
The main tasks you can perform to configure log handlers are:
  • Adding new handlers.
  • Configuring handlers.
All supported log handlers (including custom) can be configured in the management console.

12.3. Logging Configuration in the CLI

Prerequisite
The Management CLI must be running and connected to the relevant JBoss EAP instance. For further information see Section 3.4.2, “Launch the Management CLI”

12.3.1. Configure the Root Logger with the CLI

The root logger configuration can be viewed and edited using the Management CLI.
The main tasks you will perform to configure the root logger are:
  • Add log handlers to the root logger.
  • Display the root logger configuration.
  • Change the log level.
  • Remove log handlers from the root logger.

Important

When configuring a root logger in a logging profile for a standalone system, the root of the configuration path is /subsystem=logging/logging-profile=NAME/ instead of /subsystem=logging/.
For a managed domain, you must specify which profile to use. You must add the profile name to the beginning of the configuration path for a managed domain, replacing /subsystem=logging/ with /profile=NAME/subsystem=logging/.
Add a Log Handler to the Root Logger
Use the add-handler operation with the following syntax where HANDLER is the name of the log handler to be added.
/subsystem=logging/root-logger=ROOT:add-handler(name="HANDLER")
The log handler must already have been created before it can be added to the root logger.

Example 12.3. Root Logger add-handler operation

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:add-handler(name="FILE")
{"outcome" => "success"} 
Display the Contents of the Root Logger Configuration
Use the read-resource operation with the following syntax.
/subsystem=logging/root-logger=ROOT:read-resource

Example 12.4. Root Logger read-resource operation

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:read-resource                                  
{
   "outcome" => "success",
   "result" => {
        "filter" => undefined,
        "filter-spec" => undefined,
        "handlers" => [
            "CONSOLE",
            "FILE"
      ],
      "level" => "INFO"
   }
}
Set the Log Level of the Root Logger
Use the write-attribute operation with the following syntax where LEVEL is one of the supported log levels.
/subsystem=logging/root-logger=ROOT:write-attribute(name="level", value="LEVEL")

Example 12.5. Root Logger write-attribute operation to set the log level

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:write-attribute(name="level", value="DEBUG")
{"outcome" => "success"} 
Remove a Log Handler from the Root Logger
Use the remove-handler with the following syntax, where HANDLER is the name of the log handler to be removed.
/subsystem=logging/root-logger=ROOT:remove-handler(name="HANDLER")

Example 12.6. Remove a Log Handler

[standalone@localhost:9999 /] /subsystem=logging/root-logger=ROOT:remove-handler(name="FILE")
{"outcome" => "success"} 

12.3.2. Configure a Log Category in the CLI

Log categories can be added, removed and edited in the CLI.
The main tasks you will perform to configure a log category are:
  • Add a new log category.
  • Display the configuration of a log category.
  • Set the log level.
  • Add log handlers to a log category.
  • Remove log handlers from a log category.
  • Remove a log category.

Important

When configuring a log category in a logging profile for a standalone system, the root of the configuration path is /subsystem=logging/logging-profile=NAME/ instead of /subsystem=logging/.
For a managed domain, you must specify which profile to use. You must add the profile name to the beginning of the configuration path for a managed domain, replacing /subsystem=logging/ with /profile=NAME/subsystem=logging/.
Add a log category
Use the add operation with the following syntax. Replace CATEGORY with the category to be added.
 /subsystem=logging/logger=CATEGORY:add 

Example 12.7. Adding a new log category

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:add   
{"outcome" => "success"}
Display a log category configuration
Use the read-resource operation with the following syntax. Replace CATEGORY with the name of the category.
/subsystem=logging/logger=CATEGORY:read-resource 

Example 12.8. Log Category read-resource operation

[standalone@localhost:9999 /] /subsystem=logging/logger=org.apache.tomcat.util.modeler:read-resource
{
    "outcome" => "success",
    "result" => {
        "category" => "org.apache.tomcat.util.modeler",
        "filter" => undefined,
        "filter-spec" => undefined,
        "handlers" => undefined,
        "level" => "WARN",
        "use-parent-handlers" => true
    }
} 
Set the log level
Use the write-attribute operation with the following syntax. Replace CATEGORY with the name of the log category and LEVEL with the log level that is to be set.
/subsystem=logging/logger=CATEGORY:write-attribute(name="level", value="LEVEL") 

Example 12.9. Setting a log level

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:write-attribute(name="level", value="DEBUG")
{"outcome" => "success"} 
Set the log category to use the log handlers of the root logger.
Use the write-attribute operation with the following syntax. Replace CATEGORY with the name of the log category. Replace BOOLEAN with true for this log category to use the handlers of the root logger. Replace it with false if it is to use only its own assigned handlers.
/subsystem=logging/logger=CATEGORY:write-attribute(name="use-parent-handlers", value="BOOLEAN") 

Example 12.10. Setting use-parent-handlers

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:write-attribute(name="use-parent-handlers", value="true")
{"outcome" => "success"} 
Add a log handlers to a log category
Use the add-handler operation with the following syntax. Replace CATEGORY with the name of the category and HANDLER with the name of the handler to be added.
/subsystem=logging/logger=CATEGORY:add-handler(name="HANDLER") 
The log handler must already have been created before it can be added to the root logger.

Example 12.11. Adding a log handler

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:add-handler(name="AccountsNFSAsync")
{"outcome" => "success"}
Remove a log handler from a log category
Use the remove-handler operation with the following syntax. Replace CATEGORY with the name of the category and HANDLER with the name of the log handler to be removed.
/subsystem=logging/logger=CATEGORY:remove-handler(name="HANDLER")

Example 12.12. Removing a log handler

[standalone@localhost:9999 /] /subsystem=logging/logger=jacorb:remove-handler(name="AccountsNFSAsync")
{"outcome" => "success"} 
Remove a category
Use the remove operation with the following syntax. Replace CATEGORY with the name of the category to be removed.
/subsystem=logging/logger=CATEGORY:remove 

Example 12.13. Removing a log category

[standalone@localhost:9999 /] /subsystem=logging/logger=com.company.accounts.rec:remove   
{"outcome" => "success"} 

12.3.3. Configure a Console Log Handler in the CLI

Console log handlers can be added, removed and edited in the CLI.
The main tasks you will perform to configure a console log handler are:
  • Add a new console log handler.
  • Display the configuration of a console log handler.
  • Set the handler's log level.
  • Set the target for the handler's output.
  • Set the encoding used for the handler's output.
  • Set the formatter used for the handler's output.
  • Set whether the handler uses autoflush or not.
  • Remove a console log handler.

Important

When configuring a log handler in a logging profile for a standalone system, the root of the configuration path is /subsystem=logging/logging-profile=NAME/ instead of /subsystem=logging/.
For a managed domain, you must specify which profile to use. You must add the profile name to the beginning of the configuration path for a managed domain, replacing /subsystem=logging/ with /profile=NAME/subsystem=logging/.
Add a Console Log Handler
Use the add operation with the following syntax. Replace HANDLER with the console log handler to be added.
/subsystem=logging/console-handler=HANDLER:add 

Example 12.14. Add a Console Log Handler

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:add     
{"outcome" => "success"} 
Display a console log handler configuration
Use the read-resource operation with the following syntax. Replace HANDLER with the name of the console log handler.
/subsystem=logging/console-handler=HANDLER:read-resource 

Example 12.15. Display a console log handler configuration

[standalone@localhost:9999 /] /subsystem=logging/console-handler=CONSOLE:read-resource
{
    "outcome" => "success",
    "result" => {
        "autoflush" => true,
        "enabled" => true,
        "encoding" => undefined,
        "filter" => undefined,
        "filter-spec" => undefined,
        "formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
        "level" => "INFO",
        "name" => "CONSOLE",
        "named-formatter" => "COLOR-PATTERN",
        "target" => "System.out"
    }
}
Set the Log Level
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the console log handler and LEVEL with the log level that is to be set.
/subsystem=logging/console-handler=HANDLER:write-attribute(name="level", value="INFO") 

Example 12.16. Set the Log Level

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="level", value="TRACE")
{"outcome" => "success"} 
Set the Target
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the console log handler. Replace TARGET with either System.err or System.out for the system error stream or standard out stream respectively.
/subsystem=logging/console-handler=HANDLER:write-attribute(name="target", value="TARGET") 

Example 12.17. Set the Target

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="target", value="System.err")
{"outcome" => "success"} 
Set the Encoding
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the console log handler. Replace ENCODING with the name of the required character encoding system.
/subsystem=logging/console-handler=HANDLER:write-attribute(name="encoding", value="ENCODING") 

Example 12.18. Set the Encoding

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="encoding", value="utf-8")     
{"outcome" => "success"} 
Set the Formatter
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the console log handler. Replace FORMAT with the required formatter string.
/subsystem=logging/console-handler=HANDLER:write-attribute(name="formatter", value="FORMAT") 

Example 12.19. Set the Formatter

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n")
{"outcome" => "success"} 
Set the Auto Flush
Use the write-attribute operation with the following syntax. Replace HANDLER with the name of the console log handler. Replace BOOLEAN with true if this handler is to immediately write its output.
/subsystem=logging/console-handler=HANDLER:write-attribute(name="autoflush", value="BOOLEAN") 

Example 12.20. Set the Auto Flush

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:write-attribute(name="autoflush", value="true")                                  
{"outcome" => "success"} 
Remove a Console Log Handler
Use the remove operation with the following syntax. Replace HANDLER with the name of the console log handler to be removed.
/subsystem=logging/console-handler=HANDLER:remove 

Example 12.21. Remove a Console Log Handler

[standalone@localhost:9999 /] /subsystem=logging/console-handler=ERRORCONSOLE:remove
{"outcome" => "success"} 

12.3.4. Configure a File Log Handler in the CLI

File log handlers can be added, removed and edited in the CLI.
The main tasks you will perform to configure a file log handler are:
  • Add a new file log handler.
  • Display the configuration of a file log handler
  • Set the handler's log level.
  • Set the handler's appending behavior.
  • Set whether the handler uses autoflush or not.
  • Set the encoding used for the handler's output.
  • Specify the file to which the log handler will write.
  • Set the formatter used for the handler's output.
  • Remove a file log handler.

Important

When configuring a log handler in a logging profile for a standalone system, the root of the configuration path is /subsystem=logging/logging-profile=NAME/ instead of /subsystem=logging/.
For a managed domain, you must specify which profile to use. You must add the profile name to the beginning of the configuration path for a managed domain, replacing /subsystem=logging/ with /profile=NAME/subsystem=logging/.
Add a file log handler
Use the add operation with the following syntax. Replace PATH with the filename for the file that the log is being written to. Replace DIR with the name of the directory where the file is to be located. The value of DIR can be a path variable.
 /subsystem=logging/file-handler=HANDLER:add(file={"path"=>"PATH", "relative-to"=>"DIR"}) 

Example 12.22. Add a file log handler

[standalone@localhost:9999 /] /subsystem=logging/file-handler=accounts_log:add(file={"path"=>"accounts.log", "relative-to"=>"jboss.server.log.dir"})
{"outcome" => "success"} 
Display a file log handler configuration
Use the read-resource operation with the following syntax. Replace HANDLER with the name of the file log handler.
 /subsystem=logging/file-handler=HANDLER:read-resource 

Example 12.23. Using the read-resource operati