JBoss Enterprise Application Platform-6.4-Administration and Configuration Guide-En-US

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
JBoss Enterprise Application Platform 6.4 Administration and Configuration

Guide
For Use with Red Hat JBoss Enterprise Application Platform 6
Legal Notice
Co pyright 20 15 Red Hat, Inc..
This do cument is licensed by Red Hat under the Creative Co mmo ns Attributio n-ShareAlike 3.0
Unpo rted License. If yo u distribute this do cument, o r a mo dified versio n o f it, yo u must pro vide
attributio n to Red Hat, Inc. and pro vide a link to the o riginal. If the do cument is mo dified, all Red
Hat trademarks must be remo ved.
Red Hat, as the licenso r o f this do cument, waives the right to enfo rce, and agrees no t to assert,
Sectio n 4 d o f CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shado wman lo go , JBo ss, MetaMatrix, Fedo ra, the Infinity
Lo go , and RHCE are trademarks o f Red Hat, Inc., registered in the United States and o ther
co untries.
Linux is the registered trademark o f Linus To rvalds in the United States and o ther co untries.
Java is a registered trademark o f Oracle and/o r its affiliates.
XFS is a trademark o f Silico n Graphics Internatio nal Co rp. o r its subsidiaries in the United
States and/o r o ther co untries.
MySQL is a registered trademark o f MySQL AB in the United States, the Euro pean Unio n and
o ther co untries.
No de.js is an o fficial trademark o f Jo yent. Red Hat So ftware Co llectio ns is no t fo rmally
related to o r endo rsed by the o fficial Jo yent No de.js o pen so urce o r co mmercial pro ject.
The OpenStack Wo rd Mark and OpenStack Lo go are either registered trademarks/service
marks o r trademarks/service marks o f the OpenStack Fo undatio n, in the United States and o ther
co untries and are used with the OpenStack Fo undatio n's permissio n. We are no t affiliated with,
endo rsed o r spo nso red by the OpenStack Fo undatio n, o r the OpenStack co mmunity.
All o ther trademarks are the pro perty o f their respective o wners.
Abstract
This bo o k is a guide to the administratio n and co nfiguratio n o f Red Hat JBo ss Enterprise
Applicatio n Platfo rm 6 and its patch releases.
T able of Cont ent s
T able of Contents
. .hapt
C
. . . .er
. .1. .. Int
. . .roduct
. . . . . .ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . .
1.1. Ab o ut Red Hat JBo s s Enterp ris e Ap p lic atio n Platfo rm 6
5
1.2. Features o f JBo s s EAP 6
5
1.3. Ab o ut JBo s s EAP 6 O p erating Mo d es
6
1.4. Ab o ut Stand alo ne Servers
6
1.5. Ab o ut Manag ed Do mains
6
1.6 . Ab o ut the Do main Co ntro ller
1.7. Ab o ut Do main Co ntro ller Dis c o very and Failo ver
1.8 . Ab o ut Ho s t Co ntro ller
1.9 . Ab o ut Server G ro up s
1.10 . Ab o ut JBo s s EAP 6 Pro files
1.11. Manag e Servers o f Different Vers io ns
8
8
9
10
11
11
. .hapt
C
. . . .er
. .2. .. Applicat
. . . . . . . ion
. . . .Server
. . . . . .Management
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. 3. . . . . . . . . .
2 .1. JBo s s EAP Do c umentatio n Co nventio ns
13
2 .2. Start and Sto p JBo s s EAP 6
2 .3. Start and Sto p Servers
13
25
2 .4. Co nfig uratio n Files

2 .5. Files ys tem Paths
28
38
. .hapt
C
. . . .er
. .3.
. .Management
. . . . . . . . . . . .Int
. . erfaces
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4. 3. . . . . . . . . .
3 .1. Manag e the Ap p lic atio n Server
3 .2. Manag ement Ap p lic atio n Pro g ramming Interfac es (APIs )
43
43
3 .3. The Manag ement Co ns o le

3 .4. The Manag ement CLI
45
60
3 .5. Manag ement CLI O p eratio ns

3 .6 . The Manag ement CLI Co mmand His to ry
75
95
3 .7. Manag ement Interfac e Aud it Lo g g ing
97
. .hapt
C
. . . .er
. .4. .. User
. . . . .Management
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.0. 1. . . . . . . . . .
4 .1. Ab o ut JBo s s EAP Us er Manag ement
10 1
4 .2. Us er Creatio n
4 .3. Ad d -us er Sc rip t Co mmand Line Examp les
10 1
10 5
. .hapt
C
. . . .er
. .5.
. .Net
. . . work
. . . . .and
. . . Port
. . . . .Configurat
. . . . . . . . . ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.0. 8. . . . . . . . . .
5 .1. Interfac es
5 .2. So c ket Bind ing G ro up s
5 .3. IPv6
5 .4. Remo ting
10 8
113
121
124
. .hapt
C
. . . .er
. .6. .. Dat
. . . asource
. . . . . . . .Management
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1. 33
...........
6 .1. Intro d uc tio n
6 .2. JDBC Drivers
6 .3. No n-XA Datas o urc es
6 .4. XA Datas o urc es
133
135
140
144
6 .5. Datas o urc e Sec urity

6 .6 . Datab as e Co nnec tio n Valid atio n
6 .7. Datas o urc e Co nfig uratio n
6 .8 . Examp le Datas o urc es
153
154
156
16 7
. .hapt
C
. . . .er
. .7. .. Configuring
. . . . . . . . . . . Modules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.8. 2. . . . . . . . . .
7 .2. Dis ab le Sub d ep lo yment Mo d ule Is o latio n fo r All Dep lo yments
7 .3. Ad d a Mo d ule to All Dep lo yments
18 2
18 4
18 5
Administ rat ion and Configurat ion G uide

7 .3. Ad d a Mo d ule to All Dep lo yments
7 .4. Create a Cus to m Mo d ule
7 .5. Define an External JBo s s Mo d ule Direc to ry
18 5
18 6
18 8
7 .6 . Referenc e
18 9
. .hapt
C
. . . .er
. .8. .. Jsvc
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.9. 0. . . . . . . . . .
19 0
. .hapt
C
. . . .er
. .9. .. G
. .lobal
. . . . Valves
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1. 9. 5. . . . . . . . . .
9 .1. Ab o ut Valves
19 5
9 .2. Ab o ut G lo b al Valves
19 5
9 .3. Ab o ut Authentic ato r Valves
9 .4. Ins tall a G lo b al Valve
9 .5. Co nfig ure a G lo b al Valve
19 5
19 5
19 6
. .hapt
C
. . . .er
. .1. 0. .. Applicat
. . . . . . . .ion
. . .Deployment
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1.9. 8. . . . . . . . . .
10 .1. Ab o ut Ap p lic atio n Dep lo yment
19 8
10 .2. Dep lo y with the Manag ement Co ns o le
10 .3. Dep lo y with the Manag ement CLI
19 9
20 5
10 .4. Dep lo y with the HTTP API

10 .5. Dep lo y with the Dep lo yment Sc anner
20 8
20 9
10 .6 . Dep lo y with Maven

10 .7. Co ntro l the o rd er o f Dep lo yed Ap p lic atio ns o n JBo s s EAP 6
220
223
10 .8 . Define a Cus to m Direc to ry fo r Dep lo yed Co ntent
223
10 .9 . Dep lo yment Des c rip to r O verrid es

10 .10 . Ro llo ut Plan
224
225
. .hapt
C
. . . .er
. .1. 1. .. Subsyst
. . . . . . . .em
. . .Configurat
. . . . . . . . . ion
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 30
...........
11.1. Sub s ys tem Co nfig uratio n O verview
230
. .hapt
C
. . . .er
. .1. 2. .. T
. .he
. . Logging
. . . . . . . . Subsyst
. . . . . . . em
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 31
...........
12.1. Intro d uc tio n
231
12.2. Co nfig ure Lo g g ing in the Manag ement Co ns o le
241
12.3. Lo g g ing Co nfig uratio n in the CLI

12.4. Per-d ep lo yment Lo g g ing
242
278
12.5. Lo g g ing Pro files
279
12.6 . Lo g g ing Co nfig uratio n Pro p erties

12.7. Samp le XML Co nfig uratio n fo r Lo g g ing
28 3
29 0
. .hapt
C
. . . .er
. .1. 3.
. . Infinispan
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2. 9. 3. . . . . . . . . .
13.1. Ab o ut Infinis p an
13.2. Clus tering mo d es
29 3
29 3
13.3. Cac he Co ntainers
29 4
13.4. Ab o ut Infinis p an Statis tic s

13.5. Switc hing to Dis trib uted Cac he Mo d e fo r Web Ses s io n Rep lic atio n
29 6
29 6
13.6 . Enab le Infinis p an Statis tic s Co llec tio n

13.7. JG ro up s
29 7
29 9
13.8 . JG ro up s Tro ub les ho o ting
29 9
. .hapt
C
. . . .er
. .1. 4. .. JVM
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
. . 1. . . . . . . . . .
14.1. Ab o ut JVM
30 1
. .hapt
C
. . . .er
. .1. 5.
. . Web
. . . . Subsyst
. . . . . . . .em
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
. . 3. . . . . . . . . .
15.1. Co nfig ure the Web Sub s ys tem
313
15.2. Co nfig ure the HTTP Ses s io n Timeo ut
313
15.3. Servlet/HTTP Co nfig uratio n
314
T able of Cont ent s

15.3. Servlet/HTTP Co nfig uratio n
15.4. Rep lac e the Default Welc o me Web Ap p lic atio n
314
323
15.5. Sys tem Pro p erties in JBo s s Web

15.6 . Ab o ut http -o nly Ses s io n Manag ement Co o kies
323
328
. .hapt
C
. . . .er
. .1. 6. .. Web
. . . . Services
. . . . . . . . Subsyst
. . . . . . . .em
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
............
16 .1. Co nfig ure Web Servic es O p tio ns
330
16 .2. O verview o f Hand lers and Hand ler Chains
331
. .hapt
C
. . . .er
. .1. 7. .. HT
. . .T. P
. .Clust
. . . . .ering
. . . . .and
. . . Load
. . . . . Balancing
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
............
17.1. HTTP Server name c o nventio ns
334
17.2. Intro d uc tio n
17.3. Co nnec to r Co nfig uratio n
335
338
17.4. Web Server Co nfig uratio n
342
17.5. Clus tering

17.6 . Web , HTTP Co nnec to rs , and HTTP Clus tering
355
36 1
17.7. Ap ac he mo d _jk
38 7
17.8 . Ap ac he mo d _p ro xy
17.9 . Mic ro s o ft ISAPI Co nnec to r
39 8
40 2
17.10 . O rac le NSAPI Co nnec to r
40 9
. .hapt
C
. . . .er
. .1. 8. .. Messaging
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.1. 6. . . . . . . . . .
416
18 .2. Co nfig uratio n o f Trans p o rts
418
18 .3. Dead Co nnec tio n Detec tio n

18 .4. Wo rk with Larg e Mes s ag es
426
429
18 .5. Pag ing

18 .6 . Diverts
430
433
18 .7. The Client Clas s p ath
435
18 .8 . Co nfig uratio n
18 .9 . PRE_ACKNO WLEDG E mo d e
435
46 1
18 .10 . Thread Manag ement
46 3
18 .11. Mes s ag e G ro up ing

18 .12. Dup lic ate Mes s ag e Detec tio n
46 5
46 8
18 .13. JMS Brid g es

18 .14. Pers is tenc e
470
473
18 .15. Ho rnetQ Clus tering
474
18 .16 . Hig h Availab ility
48 4
18 .17. Perfo rmanc e Tuning
49 1
. .hapt
C
. . . .er
. .1. 9. .. T
. .ransact
. . . . . . ion
. . . .Subsyst
. . . . . . .em
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4.9. 6. . . . . . . . . .
19 .1. Trans ac tio n Sub s ys tem Co nfig uratio n
49 6
19 .2. Trans ac tio n Ad minis tratio n
50 4
19 .3. Trans ac tio n Referenc es
50 9
19 .4. O RB Co nfig uratio n
510
19 .5. JDBC O b jec t Sto re Sup p o rt
513
. .hapt
C
. . . .er
. .2. 0. .. Mail
. . . . subsyst
. . . . . . . em
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
. . 5. . . . . . . . . .
2 0 .1. Us e c us to m trans p o rts in mail s ub s ys tem
515
. .hapt
C
. . . .er
. .2. 1. .. Ent
. . . erprise
. . . . . . .JavaBeans
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
. . 7. . . . . . . . . .
2 1.1. Intro d uc tio n
517
2 1.2. Co nfig uring Bean Po o ls
518
2 1.3. Co nfig uring EJB Thread Po o ls
523
2 1.4. Co nfig uring Ses s io n Beans

2 1.5. Co nfig uring Mes s ag e-Driven Beans
527
533

2 1.5. Co nfig uring Mes s ag e-Driven Beans
533
2 1.6 . Co nfig uring the EJB3 Timer Servic e
534
2 1.7. Co nfig uring the EJB As ync hro no us Invo c atio n Servic e
537
2 1.8 . Co nfig uring the EJB3 Remo te Invo c atio n Servic e
537
2 1.9 . Co nfig uring EJB 2.x Entity Beans
538
. .hapt
C
. . . .er
. .2. 2. .. Java
. . . . .Connect
. . . . . . . or
. . Archit
. . . . . .ect
. . .ure
. . .(JCA)
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
. . 2. . . . . . . . . .
2 2.2. Co nfig ure the Java Co nnec to r Arc hitec ture (JCA) Sub s ys tem
542
543
2 2.3. Dep lo y a Res o urc e Ad ap ter
548
2 2.4. Co nfig ure a Dep lo yed Res o urc e Ad ap ter
549
2 2.5. Res o urc e Ad ap ter Des c rip to r Referenc e
555
2 2.6 . View Defined Co nnec tio n Statis tic s

2 2.7. Res o urc e Ad ap ter Statis tic s
558
559
2 2.8 . Dep lo y the Web Sp here MQ Res o urc e Ad ap ter
559
2 2.9 . Ins tall JBo s s Ac tive MQ Res o urc e Ad ap ter
56 5
2 2.10 . Co nfig ure a G eneric JMS Res o urc e Ad ap ter fo r Us e with a Third -p arty JMS Pro vid er
56 5
2 2.11. Co nfig uring the Ho rnetQ JCA Ad ap ter fo r Remo te Co nnec tio ns
570
. .hapt
C
. . . .er
. .2. 3.
. . Hibernat
. . . . . . . .e. Search
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
. . 4. . . . . . . . . .
2 3.1. G etting Started with Hib ernate Searc h
574
2 3.2. Co nfig uratio n
578
2 3.3. Mo nito ring
602
. .hapt
C
. . . .er
. .2. 4. .. Deploy
. . . . . . .JBoss
. . . . . .EAP
. . . .6. on
. . . Amaz
. . . . .on
. . .EC2
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.0. 4. . . . . . . . . .
604
2 4.2. Dep lo ying JBo s s EAP 6 o n Amaz o n EC2

2 4.3. No n-c lus tered JBo s s EAP 6
606
606
2 4.4. No n-c lus tered Ins tanc es
606
2 4.5. No n-c lus tered Manag ed Do mains
6 10
2 4.6 . Clus tered JBo s s EAP 6
6 17
2 4.7. Clus tered Ins tanc es

2 4.8 . Clus tered Manag ed Do mains
6 23
6 27
2 4.9 . Es tab lis hing Mo nito ring with JBo s s O p eratio ns Netwo rk (JO N)
6 33
2 4.10 . Us er Sc rip t Co nfig uratio n
6 36
2 4.11. Tro ub les ho o ting
6 39
. .hapt
C
. . . .er
. .2. 5.
. . Ext
. . . ernaliz
. . . . . .e. Sessions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.4. 0. . . . . . . . . .
2 5.1. Externaliz e HTTP Ses s io n fro m JBo s s EAP 6 .x to JBo s s Data G rid
6 40
. .ppendix
A
. . . . . . . A.
. . Supplement
. . . . . . . . . . . al
. . References
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.4. 2. . . . . . . . . .
A .1. Do wnlo ad Files fro m the Red Hat Cus to mer Po rtal
A .2. Co nfig ure the Default Java Develo p ment Kit o n Red Hat Enterp ris e Linux
6 42
6 42
A .3. Manag ement Interfac e Aud it Lo g g ing Referenc e
6 44
. .ppendix
A
. . . . . . . B.
. . .Revision
. . . . . . . .Hist
. . . ory
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.4. 7. . . . . . . . . .
Chapt er 1 . Int roduct ion
Chapter 1. Introduction
1.1. About Red Hat JBoss Ent erprise Applicat ion Plat form 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.
Report a bug
1.2. Feat ures of JBoss EAP 6

T ab le 1.1. JB o ss EAP 6 Feat u res
Feat u re
D escrip t io n
Java Certification
Java Enterprise Edition 6 Full Profile and Web

Profile certified.
Managed D omain
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
Simplified directory layout
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.
The mo d ul es directory now contains all
application server modules. The common and
server-specific l i b directories are deprecated.
The d o mai n and stand al o ne directories
contain the artifacts and configuration files for
domain and standalone deployments
respectively.
Feat u re
D escrip t io n
Modular class loading mechanism
Modules are loaded and unloaded on demand.

This improves performance, has security
benefits and reduces start-up and restart times.
D atabase drivers are deployed like other
services. In addition, datasources are created
and managed directly in the Management
Console or Management CLI.
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.
Streamlined D ata source management
Reduced and more efficient resource use
Report a bug
1.3. About JBoss EAP 6 Operat ing 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.
Report a bug
1.4 . About St andalone 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.
Report a bug
1.5. About Managed Domains
Fig u re 1.1. G rap h ical R ep resen t at io n o f a Man ag ed D o main

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 d o mai n. sh or d o mai n. 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.
Report a bug
1.6. About t he Domain Cont roller

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 d o mai n/co nfi g urati o n/d o mai n. xml
file. This file is in the unzipped JBoss EAP 6 installation file, on the domain controller's host's
filesystem.
A d o mai n. xml file must be located in the d o mai n/co nfi g urati o n/ 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 d o mai n. xml file on
such a server does no harm, however.
The d o mai n. 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.
Report a bug
1.7. About Domain Cont roller 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 its been
promoted.
The following is an example of how to configure a host controller with multiple options for finding the
domain controller.
Examp le 1.1. H o st co n t ro ller co n f ig u red wit h mu lt ip le d o main co n t ro ller o p t io n s

<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:

n ame
The name for this domain controller discovery option
h o st
The remote domain controller's host name.
p o rt
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.
Pro ced u re 1.1. Pro mo t in g a h o st co n t ro ller t o b e t h e d o main co n t ro ller

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.
/ho st= HOST_NAME: wri te-l o cal -d o mai n-co ntro l l er
4. Execute the following command to reload the host controller.
rel o ad --ho st= HOST_NAME
The host controller chosen in step 2 will now act as the domain controller.
Report a bug
1.8. About Host Cont roller
A host controller is launched when the d o mai n. sh or d o mai n. 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
d o mai n/co nfi g urati o n/ho st. xml file located in the unzipped JBoss EAP 6 installation file on
its host's filesystem. The ho st. 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 d o mai n. xml can be mapped to an actual machine-specific IP address in
ho st. xml . And abstract path names in domain.xml can be mapped to actual filesystem paths in
ho st. xml .
Report a bug
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. D ifferent server groups can be configured with
different profiles and deployments. A domain can be configured with different server tiers providing
different services, for example.
D ifferent 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:
Examp le 1.2. Server g ro u p d ef in it io n

<server-group name="main-server-group" profile="default">
<socket-binding-group ref="standard-sockets"/>
10
<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 ho st. 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 ho st. 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).
Report a bug
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.
Report a bug
1.11. Manage Servers of Different Versions
11
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
d o mai n. xml must be the o l d est 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 fo rmatter] 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
Report a bug
12
Chapt er 2 . Applicat ion Server Management
Chapter 2. Application Server Management

2.1. JBoss EAP Document at ion Convent ions
All instances of EAP_HOME in this guide refer to the JBoss EAP root installation directory, which
depends on the installation method you used.
Z ip In st allat io n Met h o d
EAP_HOME refers to the directory in which the JBoss EAP Z IP file was extracted.
In st aller Met h o d
EAP_HOME refers to the directory in which you chose to install JBoss EAP.
R PM In st allat io n Met h o d
EAP_HOME refers to the directory /usr/share/jbo ssas.
Note
The notation EWS_HOME is used to refer to JBoss EWS installation locations following the
same conventions outlined above for JBoss EAP.
Report a bug
2.2. St art and St op JBoss EAP 6

2.2.1. St art JBoss EAP 6
JBoss EAP runs in one of two modes, Standalone Server or Managed D omain, 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.
T ab le 2.1. C o mman d s t o st art JB o ss EAP
O p erat in g Syst em
St an d alo n e Server
Man ag ed D o main
Red Hat Enterprise Linux
EAP_HOME/bi n/stand al o ne
. sh
EAP_HOME\bi n\stand al o ne
. bat
EAP_HOME/bi n/d o mai n. sh
Microsoft Windows Server
EAP_HOME\bi n\d o mai n. bat
For more information on how to start JBoss EAP 6, refer Section 2.2.2, Start JBoss EAP 6 as a
Standalone Server and Section 2.2.4, Start JBoss EAP 6 as a Managed D omain .
Report a bug
2.2.2. St art JBoss EAP 6 as a St andalone Server

Su mmary
13
This topic covers the steps to start JBoss EAP 6 as a Standalone Server.
Pro ced u re 2.1. St art t h e Plat f o rm Service as a St an d alo n e Server
1. Fo r R ed H at En t erp rise Lin u x.
Run the command: EAP_HOME/bi n/stand al o ne. sh
2. Fo r Micro so f t Win d o ws Server.
Run the command: EAP_HOME\bi n\stand al o ne. bat
3. O p t io n al: Sp ecif y ad d it io n al p aramet ers.
To list all available parameters for the start-up scripts, use the -h parameter.
R esu lt
The JBoss EAP 6 Standalone Server instance starts.
Report a bug
2.2.3. Running Mult iple JBoss EAP St andalone Servers on a Single Machine
Su mmary
This topic describes the steps for running multiple JBoss EAP Standalone servers on a single
machine.
Pro ced u re 2.2. R u n mu lt ip le in st an ces o f JB o ss EAP st an d alo n e servers o n a sin g le
mach in e
1. Create a copy of the EAP_HOME/stand al o ne/ directory directly under EAP_HOME/ for each
standalone server. For example, to create a directory for standalone servers no d e1 and
no d e2, 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 --serverconfig=SERVER_CONFIGURATION_FILE -Djboss.socket.binding.portoffset=PORT_OFFSET
a. This example starts no d e1
14
$ 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
b. This example to start no d e2 depends on whether the machine supports multiple IP
addresses.
A. 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
B. If the machine does not support multiple IP addresses, you must specify a
jbo ss. so cket. bi nd i ng . po rt-o ffset 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.
Report a bug
2.2.4 . St art JBoss EAP 6 as a Managed Domain

O rd er o f O p erat io n s
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.
Pro ced u re 2.3. St art t h e Plat f o rm Service as a Man ag ed D o main
1. Fo r R ed H at En t erp rise Lin u x.
Run the command: EAP_HOME/bi n/d o mai n. sh
2. Fo r Micro so f t Win d o ws Server.
Run the command: EAP_HOME\bi n\d o mai n. bat
3. O p t io n al: Pass ad d it io n al p aramet ers t o t h e st art - u p scrip t .
15
To list all available parameters for the start-up scripts, use the -h parameter.
R esu lt
The JBoss EAP 6 Managed D omain instance starts.
Report a bug
2.2.5. Configure t he Name of a Host in a Managed Domain

Su mmary
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 ho st element name attribute in the ho st. xml configuration file.
2. The value of the jbo ss. ho st. name system property.
3. The value that follows the final period (" ." ) character in the
jbo ss. q ual i fi ed . ho st. name system property, or the entire value if there is no final
period (" ." ) character.
4. The value that follows the period (" ." ) character in the HO ST NAME environment variable for
POSIX-based operating systems, the C O MP UT ER NAME 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.
Pro ced u re 2.4 . C o n f ig u re t h e H o st N ame U sin g a Syst em Pro p ert y
1. Open the host configuration file for editing, for example, ho st. xml .
2. Find the ho st 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 ho st element
should now look like the following example.
<host xmlns="urn:jboss:domain:1.6">
4. Start the server passing the -D jbo ss. ho st. name argument, for example:
-D jbo ss. ho st. name= HOST_NAME
Pro ced u re 2.5. C o n f ig u re t h e H o st N ame U sin g a Sp ecif ic N ame
1. Start the JBoss EAP slave host using the following syntax:
16
bi n/d o mai n. sh --ho st-co nfi g = HOST_FILE_NAME

For example:
bi n/d o mai n. sh --ho st-co nfi g = ho st-sl ave0 1. xml
2. Launch the Management CLI.
3. Use the following syntax to replace the host name:
/ho st= EXISTING_HOST_NAME: wri teattri bute(name= "name",val ue= UNIQUE_HOST_NAME)
For example:
/ho st= master: wri te-attri bute(name= "name",val ue= "ho st-sl ave0 1")
You should see the following result.
"outcome" => "success"
This modifies the host name attribute in the ho st-sl ave0 1. 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
rel o ad --ho st= EXISTING_HOST_NAME
For example:
rel o ad --ho st= master
Report a bug
2.2.6. Creat e Managed Domain on T wo 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 D omain Controller .
IP1 = IP address of the domain controller (Machine 1)
IP2 = IP address of the host (Machine 2)
Pro ced u re 2.6 . C reat e man ag ed d o main o n t wo mach in es
17
1. O n Mach in e 1
a. Use the add-user.sh script to add management user. For example, sl ave0 1, so the
host can authenticate the domain controller. Note the SEC R ET _VALUE from the ad d user output.
b. Start domain with ho st-master. xml config file, which is preconfigured for
dedicated domain controller.
c. Use -bmanag ement= $IP 1 to make domain controller visible to other machines.
EAP_HOME/bin/domain.sh --host-config=host-master.xml bmanagement=$IP1
2. O n Mach in e 2
a. Update EAP_HOME/d o mai n/co nfi g urati o n/ho st-sl ave. xml file with user
credentials.
<?xml version='1.0' encoding='UTF-8'?>
<host xmlns="urn:jboss:domain:1.6" name="slave01">

<management>
<security-realms>
<security-realm name="ManagementRealm">
<server-identities>
<secret value="$SECRET_VALUE" />

</server-identities>
...
b. Start host.
EAP_HOME/bin/domain.sh --host-config=host-slave.xml
Djboss.domain.master.address=$IP1 -b=$IP2
3. N o w we can man ag e t h e d o main .
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/
Report a bug
18
2.2.7. Creat e Managed Domain on a Single Machine

Multiple host controllers can be run on a single machine by using the jbo ss. d o mai n. base. d i r
property.
Pro ced u re 2.7. R u n Mu lt ip le H o st C o n t ro llers o n a Sin g le Mach in e
1. Copy the EAP_HOME/d o mai n directory for the domain controller.
cp -r EAP_HOME/domain /path/to/domain1
2. Copy the EAP_HOME/d o mai n directory for a host controller.
cp -r EAP_HOME/domain /path/to/host1
3. Start the domain controller using /path/to /d o mai n1.
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 /ho st1.
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
R esu lt
Each instance started in this manner will share the rest of the resources in the base installation
directory (i.e. EAP_HOME/mo d ul es/), but use the domain configuration from the directory specified
by jbo ss. d o mai n. base. d i r.
Report a bug
2.2.8. St art JBoss EAP 6 wit h an Alt ernat ive Configurat ion
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 D omain or Standalone Server, and operating system.
Prereq u isit es
Before using an alternative configuration file, prepare it using the default configuration as a
template.
For Managed D omains, alternative configuration files are stored in the
EAP_HOME/d o mai n/co nfi g urati o n/ directory.
For Standalone Servers, alternative configuration files are stored in the
EAP_HOME/stand al o ne/co nfi g urati o n/ directory.
19
Note
Example configurations are included in the EAP_HOME/d o cs/exampl es/co nfi g s/
directory. Use these examples to enable features such as clustering or the Transactions XTS
API.
St art t h e In st an ce wit h an Alt ern at ive C o n f ig u rat io n

St an d alo n e server
For a Standalone Server, provide the configuration filename using the --server-config switch.
The configuration file must be in the EAP_HOME/stand al o ne/co nfi g urati o n/ directory, and
you must specify the file path relative to this directory.
Examp le 2.1. U sin g an Alt ern at e C o n f ig u rat io n f ile f o r a St an d alo n e Server in R ed H at

En t erp rise Lin u x
[user@ host bin]$ . /stand al o ne. sh --server-co nfi g = standalonealternate.xml
This example uses the EAP_HOME/stand al o ne/co nfi g urati o n/stand al o neal ternate. xml configuration file.
Examp le 2.2. U sin g an Alt ern at e C o n f ig u rat io n f ile f o r a St an d alo n e Server in

Micro so f t Win d o ws Server
C:\EAP_HOME\bin> stand al o ne. bat --server-co nfi g = standalonealternate.xml
This example uses the EAP_HOME\stand al o ne\co nfi g urati o n\stand al o neal ternati ve. xml configuration file.
Man ag ed D o main
For a Managed D omain, provide the configuration filename using the --domain-config switch.
The configuration file must be in the EAP_HOME/d o mai n/co nfi g urati o n/ directory, and you
need to specify the path relative to that directory.
Examp le 2.3. U sin g an Alt ern at e C o n f ig u rat io n f ile f o r a Man ag ed D o main in R ed H at

En t erp rise Lin u x
[user@ host bin]$ . /d o mai n. sh --d o mai n-co nfi g = domain-alternate.xml
This example uses the EAP_HOME/d o mai n/co nfi g urati o n/d o mai n-al ternate. xml
configuration file.
Examp le 2.4 . U sin g an Alt ern at e C o n f ig u rat io n f ile f o r a Man ag ed D o main in

20
C:\EAP_HOME\bin> d o mai n. bat --d o mai n-co nfi g = domain-alternate.xml
This example uses the EAP_HOME\d o mai n\co nfi g urati o n\d o mai n-al ternate. xml
configuration file.
Report a bug
2.2.9. St op 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 D omain 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 .
Pro ced u re 2.8. St o p an in st an ce o f JB o ss EAP 6

St o p an in st an ce wh ich was st art ed in t eract ively f ro m a co mman d p ro mp t .
Press C trl -C in the terminal where JBoss EAP 6 is running.
Pro ced u re 2.9 . St o p an in st an ce wh ich was st art ed as an o p erat in g syst em service.
D epending on the operating system, use one of the following procedures.
A. R ed H at En t erp rise Lin u x
For Red Hat Enterprise Linux, if you have written a service script, use its sto p facility. This
needs to be written into the script. Then you can use servi ce scriptname sto p, where
scriptname is the name of the script.
B. Micro so f t Win d o ws Server
In Microsoft Windows, use the net servi ce command, or stop the service from the Servi ces
applet in the Control Panel.
Pro ced u re 2.10. St o p an in st an ce wh ich is ru n n in g in t h e b ackg ro u n d ( R ed H at
En t erp rise Lin u x)
1. Obtain the process ID (PID ) of the process:
A. If o n ly a sin g le in st an ce is ru n n in g ( st an d alo n e mo d e)
Either of the following commands will return the PID of a single instance of JBoss EAP 6:
pi d o f java
21
jps
(The jps command will return an ID for two processes; one for jbo ss-mo d ul es. jar
and one for jp s itself. Use the ID for jbo ss-mo d ul es. jar to stop the EAP instance)
B. If mu lt ip le EAP in st an ces are ru n n in g ( d o main mo d e)
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-o ne] XX:PermSize=256m -XX:MaxPermSize=256m -Xms1303m
...
1219 6 jboss-modules.jar -D [Server: server-two ] XX:PermSize=256m -XX:MaxPermSize=256m -Xms1303m
...
120 9 6 jboss-modules.jar -D [Ho st C o ntro l l er] -Xms64m -Xmx512m
-XX:MaxPermSize=256m
...
11872 Mai n -Xms128m -Xmx750m -XX:MaxPermSize=350m XX:ReservedCodeCacheSize=96m -XX:+UseCodeCacheFlushing
...
1124 8 jboss-modules.jar -D [Stand al o ne] -XX:+UseCompressedOops
-verbose:gc
...
1289 2 Jps
...
120 80 jboss-modules.jar -D [P ro cess C o ntro l l er] -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 120 80 0.1 0.9 3606588 36772 pts/0
Sl+ 10:09
0:01 /path/to/java -D [P ro cess C o ntro l l er] -server -Xms128m Xmx128m -XX:MaxPermSize=256m
...
username 120 9 6
22
1.0
4.1 3741304 158452 pts/0
Sl+
10:09
0:13 /path/to/java -D [Ho st C o ntro l l er] -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-o ne] -XX:PermSize=256m XX:MaxPermSize=256m -Xms1000m -Xmx1000m -server ...
username 1219 6 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 Pro cess C o n t ro ller processes are the processes to stop in
order to stop the entire domain.
The g rep utility can be used with either of these commands to identify the Pro cess
C o n t ro ller:
jps -v | g rep "P ro cess C o ntro l l er"
ps aux | g rep "P ro cess C o ntro l l er"
2. Send the process the T ER M signal, by running ki l l PID, where PID is the process ID
identified by one of the commands above.
R esu lt
Each of these alternatives shuts JBoss EAP 6 down cleanly so that data is not lost.
Report a bug
2.2.10. Reference of Swit ches and Argument s t o pass at Server Runt ime
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 stand al o ne. xml ,
d o mai n. xml , and ho st. 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.
T ab le 2.2. R u n t ime Swit ch es an d Arg u men t s
Arg u men t o r Swit ch
Mo d e
D escrip t io n
--ad mi n-o nl y
Standalone
Set the server's running type to AD MIN_O NLY .

This will cause it to open administrative
interfaces and accept management requests, but
not start other runtime services or accept end
user requests.
23
Mo d e
D escrip t io n
--ad mi n-o nl y
D omain
-b= <val ue>, -b <val ue>
Standalone,
D omain
-b<i nterface>= <val ue>
Standalone,
D omain
--backup
D omain
-c= <co nfi g >, -c

<co nfi g >
-c= <co nfi g >, -c
<co nfi g >
--cached -d c
Standalone
--d ebug [<po rt>]
Standalone
-D <name>[= <val ue>]
Standalone,
D omain
D omain
Set the host controller's running type to

AD MIN_O NLY 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.
Set system property jbo ss. bi nd . ad d ress,
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<i nterface>= <val ue> entry for setting the
bind address for other interfaces.
Set system property jbo ss. bi nd . ad d ress.
<i nterface> to the given value. For example,
-bmanag ement= IP_ADDRESS
Keep a copy of the persistent domain
configuration even if this host is not the D omain
Controller.
Name of the server configuration file to use. The
default is stand al o ne. xml .
default is d o mai n. xml .
If the host is not the D omain Controller and
cannot contact the D omain Controller at boot,
boot using a locally cached copy of the domain
configuration.
Activate debug mode with an optional argument
to specify the port. Only works if the launch
script supports it.
Set a system property.
--d o mai n-co nfi g =

<co nfi g >
-h, --hel p
--ho st-co nfi g = <co nfi g >
D omain
D omain
Standalone,
D omain
D omain
--i nterpro cess-hcad d ress= <ad d ress>
D omain
--i nterpro cess-hc-po rt=

<po rt>
--master-ad d ress=
<ad d ress>
D omain
24
D omain

default is d o mai n. xml .
D isplay the help message and exit.
Name of the host configuration file to use. The
default is ho st. xml .
Address on which the host controller should
listen for communication from the process
controller.
Port on which the host controller should listen
for communication from the process controller.
Set system property
jbo ss. d o mai n. master. ad d ress to the
given value. In a default slave Host Controller
config, this is used to configure the address of
the master Host Controller.
Mo d e
D escrip t io n
--master-po rt= <po rt>
D omain
--read -o nl y-serverco nfi g = <co nfi g >
Standalone
--read -o nl y-d o mai nco nfi g = <co nfi g >
D omain
--read -o nl y-ho stco nfi g = <co nfi g >
D omain
-P = <url >, -P <url >, -pro perti es= <url >

--pc-ad d ress= <ad d ress>
Standalone,
D omain
D omain
Set system property

jbo ss. d o mai n. master. po rt 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.
Name of the server configuration file to use. This
differs from --server-config and -c in that
the original file is never overwritten.
Name of the domain configuration file to use.
This differs from --domain-config and -c in
that the initial file is never overwritten.
Name of the host configuration file to use. This
differs from --host-config in that the initial
file is never overwritten.
Load system properties from the given URL.
--pc-po rt= <po rt>
D omain
-S<name>[= <val ue>]

--server-co nfi g =
<co nfi g >
-u= <val ue>, -u <val ue>
Standalone
Standalone
-v, -V, --versi o n
Standalone,
D omain
Standalone,
D omain
Address on which the process controller listens

for communication from processes it controls.
Port on which the process controller listens for
communication from processes it controls.
Set a security property.
default is stand al o ne. xml .
Set system property
jbo ss. d efaul t. mul ti cast. ad d ress,
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.
D isplay 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.
Report a bug
2.3. St art and St op Servers

2.3.1. St art and St op Servers Using t he Management CLI
Prereq u isit es
Section 3.4.2, Launch the Management CLI
25
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
D omain 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
D omain instances.
St o p a St an d alo n e Server wit h t h e Man ag emen t C LI
Standalone Servers, started either by a script or manually at a shell prompt, can be shut down from
the Management CLI using the shutd o wn command.
Examp le 2.5. St o p a St an d alo n e Server in st an ce via t h e Man ag emen t C LI

[standalone@ localhost:9999 /] shutdown
To restart the JBoss EAP 6 Standalone Server instance, run the instances startup script or start it
manually as described in Section 2.2.2, Start JBoss EAP 6 as a Standalone Server .
St art an d St o p a Man ag ed D o main wit h t h e Man ag emen t C LI
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.
Examp le 2.6 . St o p a Server H o st in a Man ag ed D o main via t h e Man ag emen t C LI

Similar to Standalone Server instance, the shutd o wn command is used to shut down a declared
Managed D omain 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
Examp le 2.7. St art an d St o p a Server G ro u p in a Man ag ed D o main via t h e Man ag emen t

C LI
This example starts a default server group named main-server-group by declaring the group
before calling the start and sto p operations.
[domain@ localhost:9999 /] /server-group=main-server-group:start-servers
[domain@ localhost:9999 /] /server-group=main-server-group:stop-servers
Examp le 2.8. St art an d St o p a Server In st an ce in a Man ag ed D o main via t h e

Man ag emen t C LI
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 sto p operations.
[domain@ localhost:9999 /] /host=master/server-config=server-one:start
26
[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.
Report a bug
2.3.2. St art a Server Using t he Management Console

Prereq u isit es
Section 2.2.4, Start JBoss EAP 6 as a Managed D omain
Section 3.3.2, Log in to the Management Console
Pro ced u re 2.11. St art t h e Server f o r a Man ag ed D o main
1. Select the D o mai n tab at the top of the console and then, select the T O PO LO G Y tab. In the
left navigation bar, under D o main , select O verview.
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 St art Server text when it appears. A confirmation dialogue
box will open. Click C o nfi rm to start the server.
R esu lt
The selected server is started and running.
Report a bug
2.3.3. St op a Server Using t he Management Console

Prereq u isit es
Pro ced u re 2.12. St o p a Server in a Man ag ed D o main U sin g t h e Man ag emen t C o n so le
1. Select the D o mai n tab at the top of the console and then, select the T O PO LO G Y tab. In the
left navigation bar, under D o main , select O verview.
2. A list of available Server Instances is displayed on the Ho sts, g ro ups and server
i nstances table. Servers that are running are indicated by a check mark.
27
3. Hover the cursor over the chosen server. Click on the Sto p Server text that appears. A
confirmation dialogue window will appear.
4. Click C o nfi rm to stop the server.
R esu lt
The selected server is stopped.
Report a bug
2.4 . Configurat ion Files

2.4 .1. About JBoss EAP 6 Configurat ion 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.
T ab le 2.3. C o n f ig u rat io n File Lo cat io n s
Server mo d e
Lo cat io n
domain.xml
EAP_HOME/d o mai n/co nfi g u This is the main configuration

rati o n/d o mai n. xml
file for a managed domain.
Only the domain master reads
this file. On other domain
members, it can be removed.
EAP_HOME/d o mai n/co nfi g u This file includes configuration
rati o n/ho st. xml
details specific to a physical
host in a managed domain,
such as network interfaces,
socket bindings, the name of
the host, and other hostspecific details. The ho st. xml
file includes all of the features
of both ho st-master. xml
and ho st-sl ave. xml , which
are described below. This file is
not present for standalone
servers.
EAP_HOME/d o mai n/co nfi g u This file includes only the
rati o n/ho st-master. xml
configuration details necessary
to run a server as a managed
domain master server. This file
is not present for standalone
servers.
EAP_HOME/d o mai n/co nfi g u This file includes only the
rati o n/ho st-sl ave. xml
configuration details necessary
to run a server as a managed
domain slave server. This file is
not present for standalone
servers.
host.xml
host-master.xml
host-slave.xml
28
Pu rp o se
Server mo d e
Lo cat io n
Pu rp o se
standalone.xml
EAP_HOME/stand al o ne/co n
fi g urati o n/stand al o ne. x
ml
standalone-full.xml
fi g urati o n/stand al o neful l . xml
standalone-ha.xml
fi g urati o n/stand al o neha. xml
standalone-full-ha.xml
fi g urati o n/stand al o neful l -ha. 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.
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:
. sh -c stand al o neful l . xml
This example configuration file
enables all of the default
subsystems and adds the
mo d _cl uster and JGroups
subsystems for a standalone
server, so that it can participate
in a high-availability or loadbalancing cluster. This file is
not applicable for a managed
domain. To use this
configuration, stop your server
and restart using the following
command:
. sh -c stand al o neha. 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:
. sh -c stand al o ne-ful l ha. xml
These are only the default locations. You can specify a different configuration file at runtime.
29
Note
For information about how to backup JBoss EAP 6 configuration data, refer Section 2.4.2,
Back up JBoss EAP Configuration D ata .
Report a bug
2.4 .2. Back up JBoss EAP Configurat ion Dat a

Su mmary
This topic describes the files that must be backed up in order to later restore the JBoss EAP server
configuration.
Pro ced u re 2.13. B ack U p t h e C o n f ig u rat io n D at a
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/mo d ul es/system/l ayers/base/
directory.
3. Back up any welcome content in the EAP_HOME/wel co me-co ntent/ directory.
4. Back up any custom scripts created in the EAP_HOME/bi n/ directory.
Report a bug
2.4 .3. Descript or-based Propert y 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.
D escriptor-based property replacement substitutes properties based on descriptors, allowing you to
remove assumptions about the environment from the application and the build chain. Environmentspecific 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.
D escriptor-based property replacement is enabled globally through stand al o ne. xml or
d o mai n. xml :
Examp le 2.9 . D escrip t o r- b ased p ro p ert y rep lacemen t

<subsystem xmlns="urn:jboss:domain:ee:1.2">
<spec-descriptor-property-replacement>
true
</spec-descriptor-property-replacement>
30
<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 persi stence. xml .
JBoss-specific descriptor replacement is enabled by default. When enabled, descriptors can be
replaced in the following configuration files:
jbo ss-ejb3. xml
jbo ss-app. xml
jbo ss-web. xml
*-jms. xml
*-d s. xml
For example, given a Bean with the following annotation:
Examp le 2.10. Examp le an n o t at io n

@ ActivationConfigProperty(propertyName = "connectionParameters",
propertyValue = "host=192.168.1.1;port=5445")
With descriptor-based property replacement enabled, the co nnecti o nP arameters 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: d efaul t}. 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.
Examp le 2.11. U sin g an Exp ressio n in a D escrip t o r

<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. co nnecti o n. parameters: ' ho st= 10 . 10 . 6 4 . 1;po rt= 54 4 5' }
allows the connection parameters to be overridden by a command-line supplied parameter, while
31
providing a default value.

Report a bug
2.4 .4 . Enabling or Disabling Descript or Based Propert y Replacement

Su mmary
Finite control over descriptor property replacement was introduced in jbo ss-as-ee_1_1. xsd . This
task covers the steps required to configure descriptor based property replacement.
Prereq u isit es
Section 2.2.1, Start JBoss EAP 6
D escriptor based property replacement flags have boolean values:
When set to true, property replacements are enabled.
When set to fal se, property replacements are disabled.
Pro ced u re 2.14 . jbo ss-d escri pto r-pro perty-repl acement
jbo ss-d escri pto r-pro perty-repl acement is used to enable or disable property replacement
in the following descriptors:
jbo ss-ejb3. xml
jbo ss-app. xml
jbo ss-web. xml
*-jms. xml
*-d s. xml
The default value for jbo ss-d escri pto r-pro perty-repl acement is true.
1. In the Management CLI, run the following command to determine the value of jbo ssd escri pto r-pro perty-repl acement:
/subsystem=ee:read-attribute(name="jboss-descriptor-propertyreplacement")
2. Run the following command to configure the behavior:
/subsystem=ee:write-attribute(name="jboss-descriptor-propertyreplacement",value=VALUE)
Pro ced u re 2.15. spec-d escri pto r-pro perty-repl acement
spec-d escri pto r-pro perty-repl acement is used to enable or disable property replacement in
the following descriptors:
ejb-jar. xml
32
persi stence. xml

appl i cati o n. xml
web. xml
The default value for spec-d escri pto r-pro perty-repl acement is fal se.
1. In the Management CLI, run the following command to confirm the value of specd escri pto r-pro perty-repl acement:
/subsystem=ee:read-attribute(name="spec-descriptor-propertyreplacement")
2. Run the following command to configure the behavior:
/subsystem=ee:write-attribute(name="spec-descriptor-propertyreplacement",value=VALUE)
R esu lt
The descriptor based property replacement tags have been successfully configured.
Report a bug
2.4 .5. Nest ed 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:
Examp le 2.12. N est ed exp ressio n
${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 MET A-INF/jbo ss. pro perti es file in the deployment archive. In an EAR or other
deployment type that supports subdeployments, the resolution is scoped to all subdeployments if the
MET A-INF/jbo ss. pro perti es is in the outer deployment (e.g. the EAR) and is scoped to a
subdeployment if MET A-INF/jbo ss. pro perti es is in the subdeployment archive (e.g. a WAR
inside an EAR.)
Examp le 2.13. U se a N est ed Exp ressio n in a C o n f ig u rat io n 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>
33
Using a nested expression, the value of d s_Exampl eD S could be replaced with a system
property. If a system property d ataso urce_name is assigned the value d s_Exampl eD S, 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 ${d ataso urce_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.
Examp le 2.14 . R ecu rsive Exp ressio n

Continuing the previous example, you might use the expression ${fo o } which resolves to the
expression ${VAULT : : d s_Exampl eD S: : passwo rd : : 1}, which then resolves to a value
contained in the Vault: secret.
Report a bug
2.4 .6. Configurat ion File Hist ory

The application server configuration files include stand al o ne. xml , as well as the d o mai n. xml
and ho st. 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.
Section 2.4.7, Start the Server with a Previous Configuration
Section 2.4.8, Save a Configuration Snapshot Using the Management CLI
Section 2.4.9, Load a Configuration Snapshot Using the Management CLI
Section 2.4.10, D elete a Configuration Snapshot Using Management CLI
Section 2.4.11, List All Configuration Snapshots Using Management CLI
Report a bug
2.4 .7. St art t he Server wit h a Previous Configurat ion

The following example shows how to start the application server with a previous configuration in a
standalone server with stand al o ne. xml . The same concept applies to a managed domain with
d o mai n. xml and ho st. xml respectively.
34
This example recalls a previous configuration saved automatically by the application server as
management operations modify the server model.
Examp le 2.15. St art t h e server wit h a saved co n f ig u rat io n

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/stand al o ne/co nfi g urati o n/stand al o ne_xml _hi sto ry/current
/stand al o ne. v1. xml
2. Start the server with this configuration of the backed up model by passing in the relative
filename under jbo ss. server. co nfi g . d i r.
EAP_HOME/bi n/stand al o ne. sh --serverco nfi g = stand al o ne_xml _hi sto ry/current/stand al o ne. v1. xml
R esu lt
The application server starts with the selected configuration.
Note
The domain configuration history is located in
EAP_HOME/d o mai n/co nfi g urati o n/d o mai n_xml _hi sto ry/current/d o mai n. v1. xm
l
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 --domainconfig=domain_xml_history/current/domain.v1.xml
Report a bug
2.4 .8. Save a Configurat ion Snapshot Using t he Management CLI

Su mmary
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 stand al o ne. xml configuration file, but the same process applies
to the d o mai n. xml and ho st. xml configuration files.
Prereq u isit es
35
Pro ced u re 2.16 . T ake a C o n f ig u rat io n Sn ap sh o t an d Save It

Save a sn ap sh o t
Run the take-snapsho t 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/s
napshot/20110630-172258657standalone.xml"
R esu lt
A snapshot of the current server configuration has been saved.
Report a bug
2.4 .9. Load a Configurat ion Snapshot Using t he Management CLI

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 stand al o ne. xml file, but the same process applies to the
d o mai n. xml and ho st. xml files.
Pro ced u re 2.17. Lo ad a C o n f ig u rat io n Sn ap sh o t
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/2
0110812-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/20110812191301472standalone.xml
2. Start the server with the selected configuration snapshot by passing in the filename.
EAP_HOME/bin/standalone.sh --serverconfig=standalone_xml_history/snapshot/20110913164449522standalone.xml
R esu lt
The server restarts with the configuration selected in the loaded snapshot.
Report a bug
36
2.4 .10. Delet e a Configurat ion Snapshot Using Management CLI

Prereq u isit es
The following examples use the stand al o ne. xml file, but the same process applies to the
Pro ced u re 2.18. D elet e a Sp ecif ic Sn ap sh o t
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/2
0110630-165714239standalone.xml
2. Run the : d el ete-snapsho t command to delete a specific snapshot, specifying the name of
the snapshot as in the example below.
[standalone@ localhost:9999 /] : d el ete-snapsho t(name= "20110630165714239standalone.xml")
{"outcome" => "success"}
R esu lt
The snapshot has been deleted.
Pro ced u re 2.19 . D elet e All Sn ap sh o t s
Run the : d el ete-snapsho t(name= "al l ") command to delete all snapshots as in the
example below.
[standalone@ localhost:9999 /] : d el ete-snapsho t(name= "al l ")
R esu lt
All snapshots have been deleted.
Report a bug
2.4 .11. List All Configurat ion Snapshot s Using Management CLI
Prereq u isit es
37
The following example uses the stand al o ne. xml file, but the same process applies to the
Pro ced u re 2.20. List All C o n f ig u rat io n Sn ap sh o t s
List all sn ap sh o t s
List all of the saved snapshots by running the : l i st-snapsho ts command.
[standalone@ localhost:9999 /] : l i st-snapsho ts
{
"result" => {
"directory" =>
"/home/hostname/EAP_HOME/standalone/configuration/standalone_xml_histo
ry/snapshot",
"names" => [
"20110818-133719699standalone.xml",
"20110809-141225039standalone.xml",
"20110802-152010683standalone.xml",
"20110808-161118457standalone.xml",
"20110912-151949212standalone.xml",
"20110804-162951670standalone.xml"
]
}
}
R esu lt
The snapshots are listed.
Report a bug
2.5. Filesyst em Pat hs

JBoss EAP 6 uses logical names for filesystem paths. The d o mai n. xml , ho st. xml , and
stand al o ne. 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 servers l o g directory.
Examp le 2.16 . R elat ive p at h examp le f o r t h e lo g g in g d irect o ry

<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.
T ab le 2.4 . St an d ard Pat h s
38
Valu e
D escrip t io n
java. ext. d i rs
jbo ss. ho me. d i r
user. ho me
user. d i r
java. ho me
jbo ss. server. base
.dir
jbo ss. server. d ata
.dir
jbo ss. server. co nf
ig.dir
jbo ss. server. l o g
.dir
jbo ss. server. temp
.dir
jbo ss. server. d epl
o y. d i r
jbo ss. co ntro l l er
. temp. d i r
jbo ss. d o mai n. bas
e. d i r
jbo ss. d o mai n. co n
fi g . d i r
jbo ss. d o mai n. d at
a. d i r
jbo ss. d o mai n. l o g
.dir
jbo ss. d o mai n. tem
p. d i r
jbo ss. d o mai n. d ep
l o yment. d i r
jbo ss. d o mai n. ser
vers. d i r
The Java development kit extension directory paths.

The root directory of the JBoss EAP 6 distribution.
The user home directory.
The user's current working directory.
The Java installation directory
The root directory for an individual server instance.
The directory the server will use for persistent data file storage.
The directory that contains the server configuration.
The directory the server will use for log file storage.
The directory the server will use for temporary file storage.
The directory that the server will use for storing deployed content.
The directory the host controller will use for temporary file storage.
The base directory for domain content.
The directory that contains the domain configuration.
The directory that the domain will use for persistent data file storage.
The directory that the domain will use for persistent log file storage.
The directory that the domain will use for temporary file storage.
The directory that the domain will use for storing deployed content.
The directory that the domain will use for storing outputs of the managed
domain instances.
O verrid e a Pat h
If you are running a standalone server, you can override all the jbo ss. server. * paths in one of
the two ways.
You can pass command line arguments when you start the server. For example:
bi n/stand al o ne. sh -D jbo ss. server. l o g . d i r= /var/l o g
You can modify the JAVA_O P T S variable in the server configuration file. Open the
EAP_HOME/bi n/stand al o ne. co nf 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
jbo ss. d o mai n. servers. d i r can be used to change the base directories of servers in a
managed domain.
39
Ad d a C u st o m Pat h
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. rel ati ve. path,
Examp le 2.17. A cu st o m lo g g in g p at h
my. rel ati ve. path= /var/l o g
Report a bug
2.5.1. Direct ory Grouping

In domain mode, each server's files are stored in the EAP_HOME/d o mai n/ directory. Subdirectories
are named according to the d i recto ry-g ro upi ng attribute, either by server or file type.
D irect o ry G ro u p in g b y 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.
Examp le 2.18. D irect o ry G ro u p in g b y Server

If JBoss EAP is installed using the Z ip 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 d i recto ry-g ro upi ng 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="byserver")
This will update the controller's ho st. 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">
40
</server>
</servers>
D irect o ry G ro u p in g b y T yp e
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 ho st. 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>
Examp le 2.19 . D irect o ry G ro u p in g b y T yp e

If JBoss EAP is installed using the Z ip 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
Report a bug
2.5.2. Use Case: Overriding Direct ories

In this example, the objective is to store domain files in the /o pt/jbo ss_eap/d ata/d o mai n_d ata
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 al l _l o g s
D ata files stored in the subdirectory al l _d ata
41
Temporary files stored in the subdirectory al l _temp

Servers' files stored in the subdirectory al l _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
...
Report a bug
42
Chapt er 3. Management Int erfaces
Chapter 3. Management Interfaces

3.1. Manage t he Applicat ion 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.
Report a bug
3.2. Management Applicat ion Programming Int erfaces (APIs)

H T T P 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 D omain 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.
43
Examp le 3.1. H T T P API C o n f ig u rat io n File Examp le

<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.
T ab le 3.1. U R Ls t o access t h e Man ag emen t C o n so le o r exp o sed H T T P API
URL
D escrip t io n
http: //l o cal ho st: 9 9 9 0 /co nso l e
The Management Console accessed on the

local host, controlling the Managed D omain
configuration.
The Management Console accessed remotely,
naming the host and controlling the Managed
D omain configuration.
The HTTP Management API runs on the same
port as the Management Console, displaying the
raw attributes and values exposed to the API.
http: //hostname: 9 9 9 0 /co nso l e
http: //hostname: 9 9 9 0 /manag ement
Examp le 3.2. R et rieve at t rib u t e valu es u sin g t h e H T T P API

The following URL retrieves the HTTP web connector attribute values (the default operation is
read -reso urce).
http://hostname:9990/management/subsystem/web/connector/http
Examp le 3.3. R et rieve a sin g le at t rib u t e valu e u sin g t h e H T T P API

The following URL retrieves the enabl ed attribute for the ExampleD S datasource.
http://hostname:9990/management/subsystem/datasources/datasource/ExampleDS?operation=attribute& name=enabled
See Section 10.4.1, D eploy an application using the HTTP API for instructions on deploying
applications using the HTTP API.
N at ive API
The Management CLI is a Native API tool. It is available for a Managed D omain 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.
44
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.
Examp le 3.4 . N at ive API C o n f ig u rat io n File Examp le

<management-interfaces>
<native-interface security-realm="ManagementRealm">
<socket-binding native="management-native"/>
</native-interface>
[...]
</management-interfaces>
Report a bug
3.3. T he 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 D omain, server instances and server groups in the same domain can be centrally
managed from the Management Console of the domain controller.
Report a bug
3.3.2. Log in t o t he Management Console

Prereq u isit es
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.
45
Fig u re 3.1. Lo g in screen f o r t h e Man ag emen t C o n so le

R esu lt
Once logged in, you are redirected to the following address and the Management Console landing
page appears: http://localhost:9990/console/App.html#home
Report a bug
3.3.3. Change t he Language of t he 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.
Su p p o rt ed Lan g u ag es
German (de)
Simplified Chinese (zh-Hans)
Brazilian Portuguese (pt-BR)
French (fr)
Spanish (es)
Japanese (ja)
Pro ced u re 3.1. C h an g e t h e Lan g u ag e o f t h e Web - b ased Man ag emen t C o n so le
1. Lo g in t o t h e Man ag emen t C o n so le.
Log into the web-based Management Console.
2. O p en t h e Set t in g s d ialo g .
Near the bottom right of the screen is a Setti ng s label. Click it to open the settings for the
Management Console.
3. Select t h e d esired lan g u ag e.
Select the desired language from the Lo cal e selection box. Select Save. A confirmation box
informs you that you need to reload the application. Click C o nfi rm. The system refreshes
your web browser automatically to use the new locale.
46
Report a bug
3.3.4 . Analyt ics in JBoss EAP Console

Ab o u t G o o g le An alyt ics
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.
Ab o u t G o o g le An alyt ics in JB o ss EAP Man ag emen t C o n so le
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.
Report a bug
3.3.5. Enable Google Analyt ics in JBoss EAP Console

To enable Google Analytics in JBoss EAP Management Console:
Log in to the Management Console
Click Setti ng s on the Management Console
47
Fig u re 3.2. Lo g in screen o f t h e Man ag emen t C o n so le

Select Enabl e Usag e D ata C o l l ecti o n checkbox on the Setti ng s dialog and click Save
button. Confirm the application reload to activate the new settings.
48
Fig u re 3.3. Set t in g s d ialo g ( En ab le U sag e D at a C o llect io n )

Report a bug
3.3.6. Disable Google Analyt ics in JBoss EAP Console

To disable Google Analytics in JBoss EAP Management Console:
Log in to the Management Console
Click Setti ng s on the Management Console
49
Fig u re 3.4 . Lo g in screen o f t h e Man ag emen t C o n so le

Uncheck the Enabl e Usag e D ata C o l l ecti o n option on the Setti ng s dialog to remove the
selection. Click Save button. Confirm the application reload to activate the new settings.
50
Fig u re 3.5. Set t in g s d ialo g ( D isab le U sag e D at a C o llect io n )

Report a bug
3.3.7. Configure a Server Using t he Management Console

Prereq u isit es
Pro ced u re 3.2. C o n f ig u re t h e Server
1. Select the D o mai n tab from the top of the console. Available server instances will be
displayed in a table.
2. Click Server C o nfi g urati o ns.
The Server C o nfi g urati o ns panel for the relevant host appears.
3. Select the server instance from the Avai l abl e Server C o nfi g urati o ns table.
4. Click Ed i t above the details of the chosen server.
5. Make changes to the configuration attributes.
51
6. Click Save to finish.
Fig u re 3.6 . Server co n f ig u rat io n

R esu lt
The server configuration is changed, and will take effect next time the server restarts.
Report a bug
3.3.8. Add a Deployment in t he Management Console

Prereq u isit es
1. Select the D epl o yments tab at the top of the console.
2. Select Ad d on the C o ntent R epo si to ry tab. A C reate D epl o yment dialog box appears.
52
Fig u re 3.7. Man ag e st an d alo n e d ep lo ymen t s

3. In the dialog box, click Bro wse. Browse to the file you want to deploy, select it and upload it.
Click Next to proceed.
Fig u re 3.8. D ep lo ymen t select io n

4. Verify the deployment name and runtime name that appear in the C reate D epl o yments
dialog box. Click Save to upload the file once the names are verified.
R esu lt
53
R esu lt
The selected content is uploaded to the server and is now ready for deployment.
Report a bug
3.3.9. Creat e a New Server in t he Management Console

Prereq u isit es
Pro ced u re 3.3. C reat e a N ew Server C o n f ig u rat io n
1. N avig at e t o t h e Server C o nfi g urati o ns p ag e in t h e Man ag emen t C o n so le
Select the D o mai n tab from the top of the console.
Fig u re 3.9 . Server C o n f ig u rat io n

2. Click Server C o nfi g urati o ns in the left menu.
3. C reat e a n ew co n f ig u rat io n
a. Select the Ad d button above the Avai l abl e Server C o nfi g urati o ns table.
b. Enter the basic server settings in the C reate Server C o nfi g urati o n dialog.
c. Select the Save button to save the new Server Configuration.
54
Fig u re 3.10. C reat e a n ew co n f ig u rat io n

Report a bug
3.3.10. Change t he Default Log Levels Using t he Management Console

Pro ced u re 3.4 . Ed it t h e Lo g g in g Levels
1. N avig at e t o t h e Lo g g i ng p an el in t h e Man ag emen t C o n so le
a. If you are working with a managed domain, select the C o nfi g urati o n tab at the top
of the console, then select the relevant profile from the drop-down list on the left of the
console.
b. For either a managed domain or a standalone server, expand the C o re menu from
the list on the left of the console and click the Lo g g i ng entry.
c. Click on the Lo g C ateg o ri es tab in the top of the console.
55
Fig u re 3.11. Lo g g in g p an el
2. Ed it lo g g er d et ails
Edit the details for any of the entries in the Lo g C ateg o ri es table.
a. Select an entry in the Lo g C ateg o ri es table, then click Ed i t in the D etai l s
section below.
b. Set the log level for the category with the Lo g Level drop-down box. Click the Save
button when done.
R esu lt
The log levels for the relevant categories are now updated.
Report a bug
3.3.11. Creat e a New Server Group in t he Management Console

Prereq u isit es
Pro ced u re 3.5. C o n f ig u re an d Ad d a n ew Server G ro u p
1. N avig at e t o t h e Server G ro ups view
Select the D o mai n tab from the top of the console.
2. Select Server G ro ups in the left hand column.
56
Fig u re 3.12. T h e Server G ro ups view

3. Ad d a server g ro u p
Click the Ad d button to add a new server group.
4. C o n f ig u re t h e server g ro u p
a. Enter a name for the server group.
b. Select the profile for the server group.
c. Select the socket binding for the server group.
d. Click the Save button to save your new group.
57
Fig u re 3.13. T h e C reate Server G ro up d ialo g

R esu lt
The new server group is visible in the Management Console.
Report a bug
3.3.12. Viewing Logs in t he 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 jbo ss. server. l o g . d i r
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.
Prereq u isit es
Pro ced u re 3.6 . View JB o ss EAP 6 Lo g s in t h e Man ag emen t C o n so le
1. Select the R u n t ime tab from the top of the Management Console.
a. If you are using a Managed D omain, use the C hang e Server button on the left menu
to select the JBoss EAP 6 server that you want to view the logs of.
2. Expand the Plat f o rm menu on the left, and select Lo g Viewer.
3. Select a log file from the list, and click the Vi ew button.
You can also click D o wnl o ad to download the log file to your local machine.
58
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 LO G FILES tab and repeating the previous
step.
Report a bug
3.3.13. Cust omer Port al Int egrat ion in t he 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: R ed Hat Access.
Clicking on this menu will reveal three task-specific links to the Customer Portal:
Search C usto mer P o rtal
O pen C ase
Mo d i fy C ase
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.
Se arch Cust o m e r Po rt al
Clicking on Search C usto mer P o rtal 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.
Ope n Case
The O pen C ase page allows you to open a new support case.
59
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.
Mo dify Case
The Mo d i fy C ase 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.
Report a bug
3.4 . T he Management CLI

3.4 .1. About t he Management Command Line Int erface (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.
Report a bug
3.4 .2. Launch t he Management CLI

Prereq u isit es:
Section 2.2.2, Start JBoss EAP 6 as a Standalone Server
Pro ced u re 3.7. Lau n ch C LI in Lin u x o r Micro so f t Win d o ws Server
A. Lau n ch t h e C LI in Lin u x
Run the EAP_HOME/bi n/jbo ss-cl i . sh file by entering the following at a command line:
$ EAP_HOME/bin/jboss-cli.sh
B. Lau n ch t h e C LI in Micro so f t Win d o ws Server
Run the EAP_HOME\bi n\jbo ss-cl i . bat file by double-clicking it, or by entering the
following at a command line:
C:\>EAP_HOME\bin\jboss-cli.bat
Report a bug
60
3.4 .3. Quit t he Management CLI

From the Management CLI, enter the q ui t command:
[domain@ localhost:9999 /] q ui t
Report a bug
3.4 .4 . Connect t o a Managed Server Inst ance Using t he Management CLI

Prereq u isit es
Pro ced u re 3.8. C o n n ect t o a Man ag ed Server In st an ce
R u n t h e co nnect co mman d
From the Management CLI, enter the co nnect command:
[disconnected /] co nnect
Connected to domain controller at localhost:9999
A. Alternatively, to connect to a managed server when starting the Management CLI on a Linux
system, use the --connect parameter:
$ EAP_HOME/bi n/jbo ss-cl i . sh --co nnect
B. The --connect parameter can be used to specify the host and port of the server. To connect
to the address 19 2. 16 8. 0 . 1 with the port value 9 9 9 9 the following would apply:
$ EAP_HOME/bi n/jbo ss-cl i . sh --co nnect -co ntro l l er= 19 2. 16 8. 0 . 1: 9 9 9 9
Report a bug
3.4 .5. Obt ain Help wit h t he Management CLI

Su mmary
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.)
Prereq u isit es
1. Fo r g en eral h elp
From the Management CLI, enter the hel p command:
61
[standalone@ localhost:9999 /] hel p

2. O b t ain co n t ext - sen sit ive h elp
From the Management CLI, enter the hel p -co mmand s extended command:
[standalone@ localhost:9999 /] hel p --co mmand s
3. For a more detailed description of a specific command, enter the command, followed by -help.
[standalone@ localhost:9999 /] deploy --hel p
R esu lt
The CLI help information is displayed.
Report a bug
3.4 .6. Use t he Management CLI in Bat ch Mode

Su mmary
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.
Prereq u isit es
Section 3.4.4, Connect to a Managed Server Instance Using the Management CLI
Pro ced u re 3.9 . B at ch Mo d e C o mman d s an d O p erat io n s
1. En t er b at ch mo d e
Enter batch mode with the batch command.
[standalone@ localhost:9999 /] batch
Batch mode is indicated by the hash symbol (#) in the prompt.
2. Ad d o p erat io n req u est s t o t h e b at ch
Once in batch mode, enter operation requests as normal. The operation requests are added
to the batch in the order they are entered.
62
Refer to Section 3.4.8, Use Operations and Commands in the Management CLI for details
on formatting operation requests.
3. R u n t h e b at ch
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. B at ch co mman d s st o red in ext ern al f iles
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 myscri pt. 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 myscri pt. txt file.
[standalone@ localhost:9999 /] batch --file=myscript.txt
The following will instantly run the batch commands stored in the file myscri pt. txt
[standalone@ localhost:9999 /] run-batch --file=myscript.txt
R esu lt
The entered sequence of operation requests is completed as a batch.
Report a bug
3.4 .7. CLI Bat ch 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.
T ab le 3.2. C LI B at ch Mo d e C o mman d s
C o mman d N ame
D escrip t io n
list-batch
List of the commands and operations in the

current batch.
Edit a line in the current batch by providing the
line number to edit and the edited command.
Example: ed i t-batch-l i ne 2 d ataso urce d i sabl e --name= Exampl eD S.
edit-batch-line line-number edited-command
63
C o mman d N ame
D escrip t io n
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: mo ve-batch-l i ne 3 1.
Remove the batch command at the specified
line. Example: remo ve-batch-l i ne 3.
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.
remove-batch-line linenumber
holdback-batch [batchname]
If you provide a batchname while using

ho l d back-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
D icards the currently active batch.
Report a bug
3.4 .8. Use Operat ions and Commands in t he Management CLI

Prereq u isit es
Pro ced u re 3.10. C reat e, C o n f ig u re an d Execu t e R eq u est s
1. C o n st ru ct t h e o p erat io n req u est
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 (()).
a. D et ermin e t h e ad d ress
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:
64
/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/stand al o ne/co nfi g urati o n/stand al o ne. xml file holds the
configuration for a standalone server and the
EAP_HOME/d o mai n/co nfi g urati o n/d o mai n. xml and
EAP_HOME/d o mai n/co nfi g urati o n/ho st. xml files hold the configuration for a
managed domain.
Note
Running the CLI commands in D omain Mode requires host and server
specification. For example, /ho st= master/server= servero ne/subsystem= l o g g i ng
Examp le 3.5. Examp le o p erat io n ad d resses

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
b. D et ermin e t h e o p erat io n
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 -o perati o n-names operation on any resource address in a
standalone server to list the available operations.
Examp le 3.6 . Availab le o p erat io n s
65
To list all available operations for the logging subsystem, enter the following
request for a standalone server:
[standalone@ localhost:9999 /] /subsystem=logging:readoperation-names
{
"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"
]
}
c. D et ermin e an y p aramet ers

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 -o perati o nd escri pti o n command on a resource node, passing the operation name as a
parameter. Refer to Example 3.7, D etermine operation parameters for details.
Examp le 3.7. D et ermin e o p erat io n p aramet ers

To determine any required parameters for the read -chi l d ren-types operation
on the logging subsystem, enter the read -o perati o n-d escri pti o n command
as follows:
[standalone@ localhost:9999 /] /subsystem=logging:readoperation-description(name=read-children-types)
{
"result" => {
"operation-name" => "read-children-types",
66
"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. En t er t h e f u ll o p erat io n req u est

Once the address, operation, and any parameters have been determined, enter the full
operation request.
Examp le 3.8. Examp le o p erat io n req u est

[standalone@ localhost:9999 /] /subsystem= web/co nnecto r= http: read reso urce(recursi ve= true)
R esu lt
The management interface performs the operation request on the server configuration.
Report a bug
3.4 .9. Use if-else Cont rol Flow wit h t he Management CLI
The Management CLI supports i f-el se control flow, which allows you to choose which set of
commands and operations to execute based on a condition. The i f condition is a boolean
expression which evaluates the response of the management command or operation specified after
the o f keyword.
Expressions can contain any of the following items:
Conditional operators (&&, ||)
Comparison operators (>, >=, <, <=, ==, !=)
Parentheses to group and prioritize expressions
Examp le 3.9 . U sin g an i f st at emen t wit h Man ag emen t C LI co mman d s

This example attempts to read the system property test. If o utco me 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
67
The condition above uses o utco me, which is returned when the CLI command after the o f
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
}
Examp le 3.10. U sin g an i f- el se st at emen t wit h Man ag emen t C LI co mman d s

This example checks the launch type of the server process (ST AND ALO NE or D O MAIN) and issues
the appropriate CLI command to enable the Exampl eD S datasource.
if (result == STANDALONE) of /:read-attribute(name=launch-type)
/subsystem=datasources/data-source=ExampleDS:writeattribute(name=enabled, value=true)
else
/profile=full/subsystem=datasources/data-source=ExampleDS:writeattribute(name=enabled, value=true)
end-if
Management CLI commands with i f-el se control flow can be specified in a file (one per line) and
passed to the jbo ss-cl i . sh script to be executed non-interactively.
EAP_HOME/bin/jboss-cli.sh --connect --file=CLI_FILE
Note
The use of nested i f-el se statements is not supported.
Report a bug
3.4 .10. Management CLI Configurat ion Opt ions

The Management CLI configuration file - jbo ss-cl i . xml - is loaded each time the CLI is started. It
must be located either in the directory $EAP_HOME/bi n or a directory specified in the system
property jbo ss. cl i . co nfi g .
d efaul t-co ntro l l er
Configuration of the controller to which to connect if the co nnect command is executed
without any parameters.
d ef au lt - co n t ro ller Paramet ers
ho st
Hostname of the controller. D efault: l o cal ho st.
68
po rt
Port number on which to connect to the controller. D efault: 9999.
val i d ate-o perati o n-req uests
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. D efault: true.
hi sto ry
This element contains the configuration for the commands and operations history log.
hi sto ry Paramet ers
enabl ed
Indicates whether or not the hi sto ry is enabled. Type: Boolean. D efault: true.
f ile- n ame
Name of the file in which the history is to be stored. D efault = . jbo ss-cl i hi sto ry.
f ile- d ir
D irectory in which the history is to be stored. D efault = $USER _HO ME
maxsiz e
Maximum size of the history file. D efault: 500.
reso lve- p aramet er- valu es
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. D efault = fal se.
co n n ect io n - t imeo u t
The time allowed to establish a connection with the controller. Type: Integer. D efault: 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 Paramet ers

vau lt
Type: vaul tT ype
69
key- st o re
Type: string.
key- st o re- p asswo rd
Type: string.
alias
Type: string
key- p asswo rd
Type: string
t ru st - st o re
Type: string.
t ru st - st o re- p asswo rd
Type: string.
mo d if y- t ru st - st o re
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. D efault:
true.
vaul tT ype
If neither co d e nor mo d ul e are specified, the default implementation will be used. If co d e
is specified but not mo d ul e, it will look for the specified class in the Picketbox module. If
mo d ul e an d co d e are specified, it will look for the class specified by co d ein the module
specified by 'module'.
co d e
Type: String.
mo d u le
Type: String
si l ent
Specifies if informational and error messages are to be output to the terminal. Even if the
fal se 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 >.
D efault: Fal se.
Report a bug
3.4 .11. Reference of Management CLI Commands

Prereq u isit es
70
Su mmary
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.
T ab le 3.3.
C o mman d
D escrip t io n
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.
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 nodetype. In that case, to execute an operation specifying a nodename would be sufficient, such as logging:read-resource.
Clears the screen.
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.
Connects to the controller on the specified host and port.
D efines a connection factory.
Manages JD BC datasource configurations in the datasource
subsystem.
D eploys 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.
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.
cd
cl ear
co mmand
co nnect
co nnecti o n-facto ry
d ata-so urce
d epl o y
echo
Example:
echo Phase one complete
hel p
D isplays the help message. Can be used with the --commands

argument to provide context sensitive results for the given
commands.
71
C o mman d
D escrip t io n
hi sto ry
D isplays 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.
D efines a JMS queue in the messaging subsystem.
D efines a JMS topic in the messaging subsystem.
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.
Prints the full node path of the current working node.
Terminates the command line interface.
Prints the value and, depending on the arguments, the
description of the attribute of a managed resource.
D isplays the description of a specified operation, or lists all
available operations if none is specified.
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.
Prints the application server version and environment
information.
Manages JD BC XA datasource configuration in the datasource
subsystem.
jms-q ueue
jms-to pi c
ls
pwd
q ui t
read -attri bute
read -o perati o n
und epl o y
versi o n
xa-d ata-so urce
Report a bug
3.4 .12. Reference of Management CLI Operat ions

Exp o sin g o p erat io n s in t h e Man ag emen t C LI
Operations in the Management CLI can be exposed by using the read -o perati o n-names
operation described in the topic Section 3.5.5, D isplay the Operation Names using the Management
CLI . The operation descriptions can be exposed by using the read -o perati o n-d escri pti o ns
operation described in the topic Section 3.5.4, D isplay an Operation D escription using the
Management CLI .
T ab le 3.4 . Man ag emen t C LI o p erat io n s
O p erat io n N ame
D escrip t io n
ad d -namespace
Adds a namespace prefix mapping to the namespaces attribute's

map.
Adds a schema location mapping to the schema-locations
attribute's map.
D eletes a snapshot of the server configuration from the
snapshots directory.
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.
Lists the snapshots of the server configuration saved in the
D isplays the value of an attribute for the selected resource.
ad d -schema-l o cati o n
d el ete-snapsho t
ful l -repl aced epl o yment
l i st-snapsho ts
read -attri bute
72
O p erat io n N ame
D escrip t io n
read -chi l d ren-names
D isplays the names of all children under the selected resource

with the given type.
D isplays information about all of a resource's children that are of
a given type.
D isplays the type names of all the children under the selected
resource.
Reads the current configuration and displays it in XML format.
D isplays the details of an operation on the given resource.
read -chi l d ren-reso urces

read -chi l d ren-types
read -co nfi g -as-xml
read -o perati o nd escri pti o n
read -o perati o n-names
read -reso urce
read -reso urced escri pti o n
rel o ad
remo ve-namespace
remo ve-schema-l o cati o n
repl ace-d epl o yment
reso l ve-expressi o n
reso l ve-i nternetad d ress

server-set-restartreq ui red
shutd o wn
start-servers
sto p-servers
take-snapsho t
upl o ad -d epl o ymentbytes
upl o ad -d epl o ymentstream
upl o ad -d epl o yment-url
val i d ate-ad d ress

wri te-attri bute
D isplays the names of all the operations for the given resource.
D isplays a model resource's attribute values along with either
basic or complete information about any child resources.
D isplays the description of a resource's attributes, types of
children and operations.
Reloads the server by shutting all services down and restarting.
Removes a namespace prefix mapping from the namespaces
attribute map.
Removes a schema location mapping from the schema-locations
attribute map.
Replace existing content in the runtime with new content. The new
content must have been previously uploaded to the deployment
content repository.
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.
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.
Puts the server into a restart-required mode
Shuts down the server via a call to System. exi t(0 ).
Starts all configured servers in a Managed D omain that are not
currently running.
Stops all servers currently running in a Managed D omain.
Takes a snapshot of the server configuration and saves it to the
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.
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.
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.
Validates the operation's address.
Sets the value of an attribute for the selected resource.
73
Report a bug
3.4 .13. Propert y Subst it ut ion in t he 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.
Pro ced u re 3.11. En ab le Pro p ert y Su b st it u t io n in t h e Man ag emen t C LI
1. Open the file EAP _HO ME/bi n/jbo ss-cl i . xml .
2. Locate the resolve-parameter-values parameter and change the value to true (the
default is fal se).

<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-parametervalues 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 --pro perti es= /path/to /fi l e. pro perti es argument or one or more D key= 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 }.
Examp le 3.11. Examp le: U sin g p ro p ert ies in Man ag emen t C LI co mman d s
74
/subsystem=datasources/data-source=${datasourcename}:add(connectionurl=jdbc:oracle:thin:@ server:1521:ora1, jndi-name=java:/jboss/${name},

driver-name=${drivername})
Report a bug
3.5. Management CLI Operat ions

3.5.1. Display t he At t ribut es of a Resource wit h t he Management CLI
Prereq u isit es
Su mmary
The read -attri bute 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.
R eq u est Pro p ert ies
name
The name of the attribute to get the value for under the selected resource.
i ncl ud e-d efaul ts
A Boolean parameter that can be set to fal se to restrict the operation results to only show
attributes set by the user and ignore default values.
Pro ced u re 3.12. D isp lay t h e C u rren t R u n t ime Valu e o f a Select ed At t rib u t e
R u n t h e read -attri bute o p erat io n
From the Management CLI, use the read -attri bute operation to display the value of a resource
attribute. 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 -attri bute(name= name-of-attribute)
An advantage of the read -attri bute operation is the ability to expose the current runtime value of
a specific attribute. Similar results can be achieved with the read -reso urce operation, but only with
the addition of the i ncl ud e-runti me request property, and only as part of a list of all available
resources for that node. The read -attri bute operation is intended for fine-grained attribute
queries, as the following example shows.
Examp le 3.12. R u n t h e read -attri bute o p erat io n t o exp o se t h e p u b lic in t erf ace IP
If you know the name of the attribute that you would like to expose, you can use the read attri bute to return the exact value in the current runtime.
[standalone@ localhost:9999 /] /interface=public:read-
75
attribute(name=resolved-address)
{
"result" => "127.0.0.1"
}
The reso l ved -ad d ress attribute is a runtime value, so it is not displayed in the results of the
standard read -reso urce operation.
[standalone@ localhost:9999 /] /interface=public:read-resource
{
"result" => {
"any" => undefined,
"any-address" => undefined,
"any-ipv4-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 reso l ved -ad d ress and other runtime values, you must use the i ncl ud e-runti me
request property.
[standalone@ localhost:9999 /] /interface=public:read-resource(includeruntime=true)
{
"result" => {
"any" => undefined,
"name" => "public",
"nic" => undefined,
76
"not" => undefined,

"resolved-address" => "127.0.0.1",
"up" => undefined,
}
}
R esu lt
The current runtime attribute value is displayed.
Report a bug
3.5.2. Display t he Act ive User in t he Management CLI

Prereq u isit es
Su mmary
The who ami 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
who ami 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.
Pro ced u re 3.13. D isp lay t h e Act ive U ser in t h e Man ag emen t C LI U sin g t h e who ami
O p erat io n
R u n t h e who ami o p erat io n
From the Management CLI, use the who ami operation to display the active user account.
[standalone@ localhost:9999 /] : who ami
The following example uses the who ami operation in a standalone server instance to show that
the active user is username, and that the user is assigned to the Manag ementR eal m realm.
Examp le 3.13. U se t h e who ami in a st an d alo n e in st an ce

[standalone@ localhost:9999 /]:whoami
{
"result" => {"identity" => {
"username" => "username",
"realm" => "ManagementRealm"
}}
}
77
R esu lt
Your current active user account is displayed.
Report a bug
3.5.3. Display Syst em and Server Informat ion in t he Management CLI

Prereq u isit es
Pro ced u re 3.14 . D isp lay Syst em an d Server In f o rmat io n in t h e Man ag emen t C LI
R u n t h e versi o n co mman d
From the Management CLI, enter the versi o n command:
[domain@ localhost:9999 /] versi o n
R esu lt
Your application server version and environment information is displayed.
Report a bug
3.5.4 . Display an Operat ion Descript ion using t he Management CLI

Prereq u isit es
Pro ced u re 3.15. Execu t e t h e C o mman d in Man ag emen t C LI
R u n t h e read -o perati o n-d escri pti o n o p erat io n
From the Management CLI, use read -o perati o n-d escri pti o n 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 -o perati o n-d escri pti o n(name= nameof-operation)
Examp le 3.14 . D isp lay t h e list - sn ap sh o t s o p erat io n d escrip t io n

The following example shows the method for describing the l i st-snapsho ts operation.
[standalone@ localhost:9999 /] :read-operation-description(name=listsnapshots)
{
78
"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
}
}
R esu lt
The description is displayed for the chosen operation.
Report a bug
3.5.5. Display t he Operat ion Names using t he Management CLI

Prereq u isit es
Pro ced u re 3.16 . Execu t e t h e C o mman d in Man ag emen t C LI
R u n t h e read -o perati o n-names o p erat io n
From the Management CLI, use the read -o perati o n-names operation to display the names of
the available operations. 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 -o perati o n-names
79
Examp le 3.15. D isp lay t h e o p erat io n n ames u sin g t h e Man ag emen t C LI

The following example shows the method for describing the read -o perati o n-names operation.
[standalone@ localhost:9999 /]: read -o perati o n-names
{
"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"
]
}
R esu lt
The available operation names are displayed.
Report a bug
3.5.6. Display Available Resources using t he Management CLI

Prereq u isit es
80

Su mmary
The read -reso urce 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.
recursi ve
Whether to recursively include complete information about child resources.
recursi ve-d epth
The depth to which information about child resources should be included.
pro xi es
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 D omain Controller.
i ncl ud e-runti me
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.
i ncl ud e-d efaul ts
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.
Execu t e t h e C o mman d in Man ag emen t C LI
R u n t h e read -reso urce o p erat io n
From the Management CLI, use the read -reso urce operation to display the available resources.
[standalone@ localhost:9999 /]: read -reso urce
The following example shows how you might use the read -reso urce operation on a standalone
server instance to expose general resource information. The results resemble the stand al o ne. xml
configuration file, displaying the system resources, extensions, interfaces and subsystems installed
or configured for the server instance. These can be further queried directly.
Examp le 3.16 . U sin g t h e read -reso urce o p erat io n at t h e ro o t level

[standalone@ localhost:9999 /]:read-resource
{
"result" => {
"management-major-version" => 1,
"management-micro-version" => 0,
"management-minor-version" => 7,
81
"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,
82
"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
}
}
R u n t h e read -reso urce o p erat io n ag ain st a ch ild n o d e

The read -reso urce 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/co nnecto r= http: read -reso urce
In the following example, specific resource information about a web subsystem component can be
exposed by directing the read -reso urce operation towards the specific web subsystem node.
Examp le 3.17. Exp o se ch ild n o d e reso u rces f ro m t h e ro o t n o d e

[standalone@ localhost:9999 /] /subsystem=web/connector=http:readresource
{
"result" => {
"configuration" => undefined,
"enable-lookups" => false,
83
"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 -reso urce operation directly.
Examp le 3.18. Exp o se ch ild n o d e reso u rces b y ch an g in g d irect o ries

[standalone@ localhost:9999 /] cd subsystem=web
[standalone@ localhost:9999 subsystem=web] cd connector=http
[standalone@ localhost:9999 connector=http] :read-resource
{
"result" => {
"enabled" => true,
"executor" => undefined,
"name" => "http",
"scheme" => "http",
"secure" => false,
"ssl" => undefined,
}
}
84
U se t h e recu rsive p aramet er t o in clu d e act ive valu es in resu lt s

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 /]/i nterface= publ i c: read -reso urce(i ncl ud erunti me= true)
Compared to the previous example, the inclusion of the i ncl ud e-runti me request property
exposes additional active attributes, such as the bytes sent and bytes received by the HTTP
connector.
Examp le 3.19 . Exp o se ad d it io n al an d act ive valu es wit h t h e i ncl ud e-runti me

p aramet er
[standalone@ localhost:9999 /] /subsystem=web/connector=http:readresource(include-runtime=true)
{
"result" => {
"any" => undefined,
"name" => "public",
"nic" => undefined,
"not" => undefined,
"resolved-address" => "127.0.0.1",
"up" => undefined,
}
}
Report a bug
3.5.7. Display Available Resource Descript ions using t he Management CLI

Prereq u isit es
Execu t e t h e C o mman d in Man ag emen t C LI
85
R u n t h e read -reso urce-d escri pti o n o p erat io n

From the Management CLI, use the read -reso urce-d escri pti o n 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 -reso urce-d escri pti o n
U se o p t io n al p aramet ers
The read -reso urce-d escri pti o n operation allows the use of the additional parameters.
Use the o perati o ns parameter to include descriptions of the resource's operations.
[standalone@ localhost:9999 /]: read -reso urced escri pti o n(o perati o ns= true)
Use the i nheri ted parameter to include or exclude descriptions of the resource's inherited
operations. The default state is true.
[standalone@ localhost:9999 /]: read -reso urced escri pti o n(i nheri ted = fal se)
Use the recursi ve parameter to include recursive descriptions of the child resources.
[standalone@ localhost:9999 /]: read -reso urced escri pti o n(recursi ve= true)
Use the l o cal e parameter to get the resource description in. If null, the default locale will be
used.
[standalone@ localhost:9999 /]: read -reso urce-d escri pti o n(l o cal e= true)
Use the access-co ntro l parameter to get the information about the permissions the current
caller has for this resource.
[standalone@ localhost:9999 /]: read -reso urce-d escri pti o n(accessco ntro l = no ne)
R esu lt
D escriptions of the available resources are displayed.
Report a bug
3.5.8. Reload t he Applicat ion Server using t he Management CLI

Prereq u isit es
From the Management CLI, use the rel o ad operation to shut down all services and restart the JBoss
EAP instance. Note that the JVM itself is not restarted. When the rel o ad is complete the Management
CLI will automatically reconnect.
86
For more details on operation requests, see Section 3.4.8, Use Operations and Commands in the
Management CLI .
Examp le 3.20. R elo ad t h e Ap p licat io n Server

[standalone@ localhost:9999 /]rel o ad
Report a bug
3.5.9. Shut t he Applicat ion Server down using t he Management CLI

Prereq u isit es
Pro ced u re 3.17. Sh u t d o wn t h e Ap p licat io n Server
R u n t h e shutd o wn o p erat io n
From the Management CLI, use the shutd o wn operation to shut the server down via the
System. exi t(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 /]shutd o wn
In the domain mode, use the following command with the appropriate host name:
[domain@ localhost:9999 /]shutd o wn --ho st= 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.
87
Note
Appending the --restart= true argument to the shutd o wn command (as shown below) will
prompt the server to restart.
[standalone@ localhost:9999 /]shutd o wn --restart= true
R esu lt
The application server is shut down. The Management CLI will be disconnected as the runtime is
unavailable.
Report a bug
3.5.10. Configure an At t ribut e wit h t he Management CLI

Prereq u isit es
Su mmary
The wri te-attri bute 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.
name
The name of the attribute to set the value for under the selected resource.
val ue
The desired value of the attribute under the selected resource. May be null if the underlying
model supports null values.
Pro ced u re 3.18. C o n f ig u re a R eso u rce At t rib u t e wit h t h e Man ag emen t C LI
R u n t h e wri te-attri bute o p erat io n
From the Management CLI, use the wri te-attri bute 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.
Examp le 3.21. D isab le t h e d ep lo ymen t scan n er wit h t h e wri te-attri bute o p erat io n
The following example uses the wri te-attri bute 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.
88
[standalone@ localhost:9999 /] /subsystem=deploymentscanner/scanner=default:write-attribute(name=scan-enabled,value=false)

The results of the operation can be confirmed directly with the read -attri bute operation.
[standalone@ localhost:9999 /] /subsystem=deploymentscanner/scanner=default:read-attribute(name=scan-enabled)
{
"result" => false
}
The results can also be confirmed by listing all of the node's available resource attributes with the
read -reso urce operation. In the following example, this particular configuration shows the
scan-enabl ed attribute is now set to fal se.
[standalone@ localhost:9999 /] /subsystem=deploymentscanner/scanner=default:read-resource
{
"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
}
}
R esu lt
The resource attribute is updated.
Report a bug
3.5.11. Configure Syst em Propert ies Using t he Management CLI

Pro ced u re 3.19 . C o n f ig u re Syst em Pro p ert ies U sin g t h e Man ag emen t C LI
1. Start the JBoss EAP server.
2. Launch the Management CLI using the command for your operating system.
For Linux:
EAP_HOME/bi n/jbo ss-cl i . sh --co nnect
For Windows:
89
EAP_HOME\bi n\jbo ss-cl i . bat --co nnect

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.
A. Add a system property on a standalone server using the following syntax:
/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)
Examp le 3.22. Ad d a syst em p ro p ert y t o a st an d alo n e server

[standalone@ localhost:9999 /] /systemproperty=property.mybean.queue:add(value=java:/queue/MyBeanQue
ue)
B. 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)
Examp le 3.23. Ad d a syst em p ro p ert y t o all servers in a man ag ed d o main

[domain@ localhost:9999 /] /systemproperty=property.mybean.queue:add(value=java:/queue/MyBeanQue
ue)
{
"result" => undefined,
"server-groups" => {"main-server-group" => {"host" =>
{"master" => {
"server-one" => {"response" => {"outcome" =>
"success"}},
"server-two" => {"response" => {"outcome" =>
"success"}}
}}}}
}
C. Add a system property to a host and its server instances in a managed domain using the
following syntax:
/host=master/systemproperty=PROPERTY_NAME:add(value=PROPERTY_VALUE)
Examp le 3.24 . Ad d a syst em p ro p ert y t o a h o st an d it s servers in a d o main
90
[domain@ localhost:9999 /] /host=master/systemproperty=property.mybean.queue:add(value=java:/queue/MyBeanQue

ue)
{
{"master" => {
"success"}},
"success"}}
}}}}
}
D . Add a system property to a server instance in a managed domain using the following
syntax:
/host=master/server-config=server-one/systemproperty=PROPERTY_NAME:add(value=PROPERTY_VALUE)
Examp le 3.25. Ad d a syst em p ro p ert y t o a server in st an ce in a man ag ed

d o main
[domain@ localhost:9999 /] /host=master/server-config=serverone/systemproperty=property.mybean.queue:add(value=java:/queue/MyBeanQue
ue)
{
{"master" => {"server-one" => {"response" => {"outcome" =>
"success"}}}}}}
}
4. Read a system property.

managed domain.
A. Read a system property from a standalone server using the following syntax:
/system-property=PROPERTY_NAME:read-resource
Examp le 3.26 . R ead a syst em p ro p ert y f ro m a st an d alo n e server

[standalone@ localhost:9999 /] /systemproperty=property.mybean.queue:read-resource
{
91

"result" => {"value" => "java:/queue/MyBeanQueue"}
}
B. Read a system property from all hosts and servers in a managed domain using the
following syntax:
/system-property=PROPERTY_NAME:read-resource
Examp le 3.27. R ead a syst em p ro p ert y f ro m all servers in a man ag ed d o main

[domain@ localhost:9999 /] /systemproperty=property.mybean.queue:read-resource
{
"result" => {
"boot-time" => true,
"value" => "java:/queue/MyBeanQueue"
}
}
C. 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
Examp le 3.28. R ead a syst em p ro p ert y f ro m a h o st an d it s servers in a

d o main
[domain@ localhost:9999 /] /host=master/systemproperty=property.mybean.queue:read-resource
{
"result" => {
}
}
D . Read a system property from a server instance in a managed domain using the following
syntax:
/host=master/server-config=server-one/systemproperty=PROPERTY_NAME:read-resource
92
Examp le 3.29 . R ead a syst em p ro p ert y f ro m a server in st an ce in a man ag ed

d o main
[domain@ localhost:9999 /] /host=master/server-config=serverone/system-property=property.mybean.queue:read-resource
{
"result" => {
}
}
5. Remove a system property.

managed domain.
A. Remove a system property from a standalone server using the following syntax:
/system-property=PROPERTY_NAME:remove
Examp le 3.30. R emo ve a syst em p ro p ert y f ro m a st an d alo n e server

[standalone@ localhost:9999 /] /systemproperty=property.mybean.queue:remove
B. Remove a system property from all hosts and servers in a managed domain using the
following syntax:
/system-property=PROPERTY_NAME:remove
Examp le 3.31. R emo ve a syst em p ro p ert y f ro m all h o st s an d servers in a

d o main
[domain@ localhost:9999 /] /systemproperty=property.mybean.queue:remove
{
{"master" => {
"success"}},
93
"success"}}
}}}}
}
C. 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
Examp le 3.32. R emo ve a syst em p ro p ert y f ro m a h o st an d it s in st an ces in a

d o main
[domain@ localhost:9999 /] /host=master/systemproperty=property.mybean.queue:remove
{
{"master" => {
"success"}},
"success"}}
}}}}
}
D . Remove a system property from a server instance in a managed domain using the
following syntax:
/host=master/server-config=server-one/systemproperty=PROPERTY_NAME:remove
Examp le 3.33. R emo ve a syst em p ro p ert y f ro m a server in a man ag ed d o main

[domain@ localhost:9999 /] /host=master/server-config=serverone/system-property=property.mybean.queue:remove
{
{"master" => {"server-one" => {"response" => {"outcome" =>
"success"}}}}}}
}
94
Note
Any system property which contains the text password (regardless of case) is replaced with the
text red acted when output via logging. This improves security by avoiding having
passwords output in plain text in log files.
Report a bug
3.5.12. Creat e a New Server wit h t he Management CLI

The following example creates a new server on the host master and adds it to cl ustered -serverg ro up:
[domain@ localhost:9999 /] /host=master/server-config=clustered-server1:add(group=clustered-server-group)
Report a bug
3.6. T he Management CLI Command Hist ory

3.6.1. About t he Management CLI Command Hist ory
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 . jbo ss-cl i -hi sto ry. This history file is configured by default to record up to a maximum of
500 CLI commands.
The hi sto ry 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.
Fu n ct io n s o f t h e Man ag emen t C LI h ist o ry
Section 3.6.2, View Management CLI Command History
Section 3.6.3, Clear the Management CLI Command History
Section 3.6.4, D isable the Management CLI Command History
Section 3.6.5, Enable the Management CLI Command History
Report a bug
3.6.2. View Management CLI Command Hist ory

Prereq u isit es
Pro ced u re 3.20. View t h e Man ag emen t C LI C o mman d H ist o ry
95
R u n t h e hi sto ry co mman d
From the Management CLI, enter the hi sto ry command:
[standalone@ localhost:9999 /] hi sto ry
R esu lt
The CLI command history stored in memory since the CLI startup or the history clear command is
displayed.
Report a bug
3.6.3. Clear t he Management CLI Command Hist ory

Prereq u isit es
Pro ced u re 3.21. C lear t h e Man ag emen t C LI C o mman d H ist o ry
R u n t h e hi sto ry --cl ear co mman d
From the Management CLI, enter the hi sto ry --cl ear command:
[standalone@ localhost:9999 /] hi sto ry --cl ear
R esu lt
The history of commands recorded since the CLI startup is cleared from the session memory. The
command history is still present in the . jbo ss-cl i -hi sto ry file saved to the user's home
directory.
Report a bug
3.6.4 . Disable t he Management CLI Command Hist ory

Prereq u isit es
Pro ced u re 3.22. D isab le t h e Man ag emen t C LI C o mman d H ist o ry
R u n t h e hi sto ry --d i sabl e co mman d
From the Management CLI, enter the hi sto ry --d i sabl e command:
[standalone@ localhost:9999 /] hi sto ry --d i sabl e
R esu lt
Commands made in the CLI will not be recorded either in memory or in the . jbo ss-cl i -hi sto ry
file saved to the user's home directory.
96
Report a bug
3.6.5. Enable t he Management CLI Command Hist ory

Prereq u isit es
Pro ced u re 3.23. En ab le t h e Man ag emen t C LI C o mman d H ist o ry
R u n t h e hi sto ry --enabl e co mman d
From the Management CLI, enter the hi sto ry --enabl e command:
[standalone@ localhost:9999 /] hi sto ry --enabl e
R esu lt
Commands made in the CLI are recorded in memory and in the . jbo ss-cl i -hi sto ry file saved to
the user's home directory.
Report a bug
3.7. Management Int erface Audit Logging

3.7.1. About Management Int erface 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 /ho st= HOST_NAME to the command for a managed domain.
97
[... /] /core-service=management/access=audit:readresource(recursive=true)
Report a bug
3.7.2. Enable Management Int erface Audit Logging t o 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 /ho st= HOST_NAME to the
following command.
/core-service=management/access=audit/logger=audit-log:writeattribute(name=enabled,value=true)
Management operations are now logged to a file:
Standalone mode: EAP_HOME/stand al o ne/d ata/aud i t-l o g . l o g
D omain mode: EAP_HOME/d o mai n/d ata/aud i t-l o g . l o g
For details of all file handler attributes, see Section A.3, Management Interface Audit Logging
Reference .
Report a bug
3.7.3. Enable Management Int erface Audit Logging t o 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 /ho st= HOST_NAME to the
/co re-servi ce commands.
Pro ced u re 3.24 . En ab le Au d it Lo g g in g t o a Syslo g Server

1. En ab le Au d it Lo g g in g
Execute the following command:
[.. /]/core-service=management/access=audit/logger=audit-log:writeattribute(name=enabled,value=true)
2. C reat e a sysl o g H an d ler
98
In this example the sysl o g server is running on the same server as the JBoss EAP instance,
on port 514. Replace the values of the ho st attribute with values appropriate to your
environment.
Examp le 3.34 . Examp le syslo g h an d ler

[.. /]batch
[.. / #]/core-service=management/access=audit/sysloghandler=mysyslog:add(formatter=json-formatter)
[.. / #]/core-service=management/access=audit/sysloghandler=mysyslog/protocol=udp:add(host=localhost,port=514)
[.. /]run-batch
3. Ad d a R ef eren ce t o t h e sysl o g H an d ler

Execute the following:
[.. /]/core-service=management/access=audit/logger=auditlog/handler=mysyslog:add
R esu lt
Management interface audit log entries are logged on the sysl o g 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 rsysl o g configurations on Red Hat Enterprise Linux, refer to the
"Basi c C o nfi g urati o n o f rsysl o g " section in the System Ad mi ni strato r' s
G ui d e for Red Hat Enterprise Linux in https://access.redhat.com/documentation/enUS/Red_Hat_Enterprise_Linux/
Report a bug
3.7.4 . Disable Management Int erface Audit Logging

The audit logging to a file or a sysl o g server can be disabled by executing the following command:
/core-service=management/access=audit/logger=audit-log:writeattribute(name=enabled,value=false)
Report a bug
3.7.5. Read a Management Int erface 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.
99
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.
T ab le 3.5. Man ag emen t In t erf ace Au d it Lo g Field s
Field N ame
D escrip t io n
type
This can have the values co re, 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).
Has the value true if the operation does not change the management
model, fal se otherwise.
Has the value true if the operation was executed during the bootup
process, fal se if it was executed once the server is up and running.
The version number of the JBoss EAP instance.
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 $l o cal is used.
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.
This can have one of the following values:
r/o
booting
version
user
domainUUID
access
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
success
ops
Report a bug
100
The address of the client executing this operation.

Has the value true if the operation is successful, fal se if it was rolled
back.
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.
Chapt er 4 . User Management
Chapter 4. User Management

4 .1. About JBoss EAP User Management
D epending 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 Z IP 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 ad d -user. sh script. For
more advanced authentication and authorization options, such as LD AP or Role-Based Access
Control (RBAC), see the Core Management Authentication section of the JBoss EAP Security Architecture
document.
Report a bug
4 .2. User Creat ion

4 .2.1. Add t he User for t he Management Int erfaces
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.
Pro ced u re 4 .1. C reat e t h e In it ial Ad min ist rat ive U ser f o r t h e R emo t e Man ag emen t
In t erf aces
1. R u n t h e ad d -user. sh o r ad d -user. bat scrip t .
Change to the EAP_HOME/bi n/ directory. Invoke the appropriate script for your operating
system.
R ed H at En t erp rise Lin u x
[user@ ho st bi n]$ ./add-user.sh
C : \bi n>
add-user.bat
2. C h o o se t o ad d a Man ag emen t u ser.
101
Press ENT ER to select the default option a to add a Management user.

This user is added to the Manag ementR eal m 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 Appl i cati o nR eal m, and provides no
particular permissions. That realm is provided for use with applications.
3. En t er t h e d esired u sern ame an d p asswo rd .
When prompted, enter the username and password. You will be prompted to confirm the
password.
4. En t er g ro u p in f o rmat io n .
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. R eview t h e in f o rmat io n an d co n f irm.
You are prompted to confirm the information. If you are satisfied, type yes.
6. C h o o se wh et h er t h e u ser rep resen t s a remo t e JB o ss EAP 6 server in st an ce.
Besides administrators, the other type of user which occasionally needs to be added to
JBoss EAP 6 in the Manag ementR eal m 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. En t er ad d it io n al u sers.
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. C reat e u sers n o n - in t eract ively.
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@ ho st bi n]$ ./add-user.sh username password
To use the application realm, use the -a parameter.
[user@ ho st bi n]$ ./add-user.sh -a username password
9. You can suppress the normal output of the add-user script by passing the --si l ent
parameter. This applies only if the minimum parameters username and passwo rd have been
specified. Error messages will still be shown.
R esu lt
102
Any users you add are activated within the security realms you have specified. Users active within the
Manag ementR eal m realm are able to manage JBoss EAP 6 from remote systems.
Report a bug
4 .2.2. Pass Argument s t o t he User Management add-user Script

You can run the ad d -user. sh or ad d -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 ad d -user. sh or ad d 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 .
For examples that demonstrate how to pass arguments on the ad d -user. sh or ad d -user. bat
command, see Section 4.3.1, Create a User Belonging to a Single Group Using the D efault
Properties Files , Section 4.3.2, Create a User Belonging to Multiple Groups Using the D efault
Properties Files , Section 4.3.3, Create a User With Administrator Privileges in the D efault Realm
Using the D efault Properties Files and Section 4.3.4, Create a User Belonging to Single Group
Using Alternate Properties Files to Store the Information . .
Report a bug
4 .2.3. Add-user Command Argument s

The following table describes the arguments available for the ad d -user. sh or ad d -user. bat
command.
T ab le 4 .1. Ad d - u ser C o mman d Arg u men t s
C o mman d
Lin e
Arg u men t
Arg u men t Valu e
D escrip t io n
-a
N/A
-dc
DOMAIN_CONFIGURATION_DI
RECTORY
-sc
SERVER_CONFIGURATION_DI
RECTORY
-up
USER_PROPERTIES_FILE
This argument specifies to create a user in the

application realm. If omitted, the default is to
create a user in the management realm.
This argument specifies the domain
configuration directory that will contain the
properties files. If it is omitted, the default
directory is
EAP_HOME/d o mai n/co nfi g urati o n/.
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/stand al o ne/co nfi g urati o n/.
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 -d c argument that
specifies the alternate configuration directory.
--userproperties
103
C o mman d
Lin e
Arg u men t
Arg u men t Valu e
D escrip t io n
-g
GROUP_LIST
A comma-separated list of groups to assign to

this user.
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 -d c argument that
specifies the alternate configuration directory.
The password of the user. The password must
satisfy the following requirements:
--group
-gp
--groupproperties
-p
PASSWORD
--password
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 nonalphanumeric symbol
-u
USER_NAME
The name of the user. Only alphanumeric

characters and the following symbols are valid:
,./=@\.
REALM_NAME
The name of the realm used to secure the

management interfaces. If omitted, the default is
Manag ementR eal m.
N/A
Run the add-user script with no output to the

console.
N/A
D isplay usage information for the add-user

script.
--user
-r
--realm
-s
--silent
-h
--help
Report a bug
4 .2.4 . Specify Alt ernat e Propert ies Files for User Management Informat ion
O verview
By default, user and role information created using the ad d -user. sh or ad d -user. bat script are
stored in properties files located in the server configuration directory. The server configuration
information is stored in the EAP_HOME/stand al o ne/co nfi g urati o n/ directory and the domain
configuration information is stored in the EAP_HOME/d o mai n/co nfi g urati o n/ directory. This
topic describes how to override the default file names and locations.
Sp ecif y Alt ern at e Pro p ert ies 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.
104
To specify an alternate directory for the domain configuration, use the -d c 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-pro perti es
argument. It can be an absolute path or it can be a file name used in conjunction with the -sc or
-d c argument that specifies the alternate configuration directory.
To specify an alternate group configuration properties file, use the -g p or --g ro uppro perti es argument. It can be an absolute path or it can be a file name used in conjunction
with the -sc or -d c argument that specifies the alternate configuration directory.
Note
The ad d -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 .
Report a bug
4 .3. Add-user Script Command Line Examples

4 .3.1. Creat e a User Belonging t o a Single Group Using t he Default Propert ies
Files
Examp le 4 .1. C reat e a u ser b elo n g in g t o a sin g le g ro u p
EAP_HOME/bi n/ad d -user. sh -a -u ' appuser1' -p ' passwo rd 1! ' -g ' g uest'
This example gives the following results.

The user appuser1 is added to the following default properties files that store user information.
EAP_HOME/stand al o ne/co nfi g urati o n/appl i cati o n-users. pro perti es
EAP_HOME/d o mai n/co nfi g urati o n/appl i cati o n-users. pro perti es
The user appuser1 with group g uest is added to the default properties files that store group
information.
EAP_HOME/stand al o ne/co nfi g urati o n/appl i cati o n-ro l es. pro perti es
EAP_HOME/d o mai n/co nfi g urati o n/appl i cati o n-ro l es. pro perti es
Report a bug
105
4 .3.2. Creat e a User Belonging t o Mult iple Groups Using t he Default

Propert ies Files
Examp le 4 .2. C reat e a u ser b elo n g in g t o mu lt ip le g ro u p s
EAP_HOME/bi n/ad d -user. sh -a -u ' appuser1' -p ' passwo rd 1! ' -g
' g uest,app1g ro up,app2g ro up'

The user appuser1 is added to the following default properties files that store user information.
EAP_HOME/stand al o ne/co nfi g urati o n/appl i cati o n-users. pro perti es
EAP_HOME/d o mai n/co nfi g urati o n/appl i cati o n-users. pro perti es
The user appuser1 with groups g uest, app1g ro up, and app2g ro up is added to the default
properties files that store group information.
EAP_HOME/stand al o ne/co nfi g urati o n/appl i cati o n-ro l es. pro perti es
EAP_HOME/d o mai n/co nfi g urati o n/appl i cati o n-ro l es. pro perti es
Report a bug
4 .3.3. Creat e a User Wit h Administ rat or Privileges in t he Default Realm Using
t he Default Propert ies Files
Examp le 4 .3. C reat e a u ser wit h Ad min ist rat o r p rivileg es in t h e D ef au lt R ealm
EAP_HOME/bi n/ad d -user. sh -u ' ad mi nuser1' -p ' passwo rd 1! ' -g ' ad mi n'

The user ad mi nuser1 is added to the following default properties files that store user
information.
EAP_HOME/stand al o ne/co nfi g urati o n/mg mt-users. pro perti es
EAP_HOME/d o mai n/co nfi g urati o n/mg mt-users. pro perti es
The user ad mi nuser1 with group ad mi n is added to the default properties files that store group
information.
EAP_HOME/stand al o ne/co nfi g urati o n/mg mt-g ro ups. pro perti es
EAP_HOME/d o mai n/co nfi g urati o n/mg mt-g ro ups. pro perti es
Report a bug
4 .3.4 . Creat e a User Belonging t o Single Group Using Alt ernat e Propert ies
Files t o St ore t he Informat ion
106
Examp le 4 .4 . C reat e a u ser b elo n g in g t o sin g le g ro u p u sin g alt ern at e p ro p ert ies f iles
EAP_HOME/bi n/ad d -user. sh -a -u appuser1 -p passwo rd 1! -g app1g ro up sc /ho me/so meusername/userco nfi g s/ -up appusers. pro perti es -g p
appg ro ups. pro perti es

The user appuser1 is added to the following properties file and that file is now the default file to
store user information.
/ho me/so meusername/userco nfi g s/appusers. pro perti es
The user appuser1 with group app1g ro up is added to the following properties file and that file is
now the default file to store group information.
/ho me/so meusername/userco nfi g s/appg ro ups. pro perti es
Report a bug
107
Chapter 5. Network and Port Configuration

5.1. Int erfaces
5.1.1. About Int erfaces
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 manag ement and publ i c interface names.
The manag ement interface name can be used for all components and services that require the
management layer, including the HTTP Management Endpoint. The publ i c 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 d o mai n. xml , ho st. xml and stand al o ne. 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 stand al o ne. xml or ho st. 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 i net-ad d ress value specified for both the management
and public relative name groups.
Examp le 5.1. An in t erf ace g ro u p creat ed wit h an i net-ad d ress valu e

<interfaces>
<interface name="management">
<inet-address value="127.0.0.1"/>
</interface>
<interface name="public">
<inet-address value="127.0.0.1"/>
</interface>
</interfaces>
108
Chapt er 5. Net work and Port Configurat ion
The following example shows a global interface group. It uses the any-ad d ress element to declare
a wildcard address.
Examp le 5.2. A g lo b al g ro u p creat ed wit h a wild card d eclarat io n

<interface name="global">

<any-address/>
</interface>
The following example declares a network interface card (eth0) under a relative group called
external .
Examp le 5.3. An ext ern al g ro u p creat ed wit h an N IC valu e

<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
interfaces name. This helps in reducing configuration complexity and administration overhead
across multiple server instances.
Examp le 5.4 . A d ef au lt g ro u p creat ed wit h sp ecif ic co n d it io n al valu es

<interface name="default">

<subnet-match value="192.168.0.0/16"/>
<up/>
<multicast/>
<not>
<point-to-point/>
</not>
</interface>
Report a bug
5.1.2. Configure Int erfaces

The default interface configurations in the stand al o ne. xml and ho st. 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.
109
Examp le 5.5. D ef au lt In t erf ace C o n f ig u rat io n s

<interfaces>
<inet-address value="${jboss.bind.address.management:127.0.0.1}"/>
</interface>
<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 ho st. xml files. For example:
<servers>
<server name="server-name" group="main-server-group">
<interfaces>
<inet-address value="ip-address"/>
</interface>
</interfaces>
</server>
</servers>
Note
For the above example, substitute server-name with your actual server name and substitute ipaddress with your actual IP address.
T ab le 5.1. In t erf ace At t rib u t es an d Valu es

In t erf ace Elemen t
D escrip t io n
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.
Empty element indicating that sockets using this interface should
be bound to a wildcard address.
any-ad d ress
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-i pv4 -ad d ress
110

be bound to the IPv4 wildcard address (0.0.0.0).
In t erf ace Elemen t
D escrip t io n
any-i pv6 -ad d ress

be bound to the IPv6 wildcard address (::).
Either an IP address in IPv6 or IPv4 dotted decimal notation, or a
hostname that can be resolved to an IP 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.
interface should be whether or not it is a loopback interface.
A loopback address that may not actually be configured on the
machine's loopback interface. D iffers 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.
interface should be whether or not it supports multicast.
The name of a network interface (e.g. eth0, eth1, lo).
A regular expression against which the names of the network
interfaces available on the machine can be matched to find an
acceptable interface.
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.
interface should be whether or not it is a point-to-point interface.
interface should be whether or not it has a publicly routable
address.
interface should be whether or not an address associated with it
is site-local.
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" .
interface should be whether or not it is currently up.
interface should be whether or not it is a virtual interface.
i net-ad d ress
l i nk-l o cal -ad d ress
l o o pback
l o o pback-ad d ress
mul ti cast
ni c
ni c-match
no t
po i nt-to -po i nt
publ i c-ad d ress
si te-l o cal -ad d ress
subnet-match
up
vi rtual
C o n f ig u re In t erf ace At t rib u t es

A. C o n f ig u re In t erf ace At t rib u t es wit h t h e Man ag emen t C LI
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(inetaddress=ip-address)
111
Use the Management CLI to add new interfaces and write new values to the interface attributes.
a. Ad d a N ew In t erf ace
The ad d operation creates new interfaces as required. The ad d 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 i net-ad d ress declared as 12.0.0.2.
/interface=interfacename/:add(inet-address=12.0.0.2)
b. Ed it In t erf ace At t rib u t es
The wri te-attri bute operation writes new values to an attribute. The following
example updates the i net-ad d ress value to 12.0.0.8.
/interface=interfacename/:write-attribute(name=inet-address,
value=12.0.0.8)
c. Verif y In t erf ace At t rib u t es
Confirm that the attribute values have changed by running the read -reso urce
operation with the i ncl ud e-runti me= true parameter to expose all current values
active in the server model. For example:
[standalone@ localhost:9999 interface=public] : read reso urce(i ncl ud e-runti me= true)
B. C o n f ig u re In t erf ace At t rib u t es wit h t h e Man ag emen t C o n so le
a. Lo g in t o t h e Man ag emen t C o n so le.
Log into the Management Console of your Managed D omain or Standalone Server
instance.
b. N avig at e t o C o n f ig u rat io n t ab
Select the C o nfi g urati o n tab from the top of the screen.
Note
For D omain Mode, select a profile from the P ro fi l e drop-down menu at the top
left of the screen.
c. Select Interfaces f ro m t h e N avig at io n Men u .

Select the Interfaces menu item from the navigation menu.
d. Ad d a N ew In t erf ace
i. Click Ad d .
ii. Enter required values for Name, Inet Ad d ress and Ad d ress Wi l d card .
112
iii. Click Save.

e. Ed it In t erf ace At t rib u t es
i. Select the interface that you need to edit from the Avai l abl e Interfaces list
and click Ed i t.
ii. Enter required values for Name, Inet Ad d ress and Ad d ress Wi l d card .
iii. Click Save.
Report a bug
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 d o mai n. xml and stand al o ne. 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.
Examp le 5.6 . D ef au lt so cket b in d in g s f o r t h e st an d alo n e co n f ig u rat io n

The default socket binding groups in the stand al o ne. xml configuration file are grouped under
stand ard -so ckets. This group is also referenced to the publ i c interface, using the same
logical referencing methodology.
<socket-binding-group name="standard-sockets" defaultinterface="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}"/>
113
<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>
Examp le 5.7. D ef au lt so cket b in d in g s f o r t h e d o main co n f ig u rat io n

The default socket binding groups in the d o mai n. xml configuration file contain four groups: the
stand ard -so ckets, ha-so ckets, ful l -so ckets and the ful l -ha-so ckets groups. These
groups are also referenced to an interface called publ i c.
<socket-binding-groups>
<socket-binding-group name="standard-sockets" defaultinterface="public">

<socket-binding name="txn-recovery-environment"
port="4712"/>
<socket-binding-group name="ha-sockets" defaultinterface="public">

<socket-binding name="jgroups-mping" port="0" multicastaddress="${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" multicastaddress="${jboss
<socket-binding name="jgroups-udp-fd" port="54200"/>
<socket-binding name="modcluster" port="0" multicastaddress="224.0.1.105"
port="4712"/>
114

<socket-binding-group name="full-sockets" defaultinterface="public">

<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" multicastaddress="${jboss
.messaging.group.address:231.7.7.7}" multicastport="${jboss.messaging.group.port:9876}"/>
<socket-binding name="messaging-throughput" port="5455"/>
port="4712"/>
<socket-binding-group name="full-ha-sockets" defaultinterface="public">

<socket-binding name="jacorb" interface="unsecure"
port="3528"/>
<socket-binding name="jacorb-ssl" interface="unsecure"
port="3529"/>
<socket-binding name="jgroups-mping" port="0" multicastaddress="${jboss
<socket-binding name="jgroups-tcp" port="7600"/>
<socket-binding name="jgroups-tcp-fd" port="57600"/>
<socket-binding name="jgroups-udp" port="55200" multicastaddress="${jboss
<socket-binding name="jgroups-udp-fd" port="54200"/>
<socket-binding name="messaging-group" port="0" multicastaddress="${jboss
.messaging.group.address:231.7.7.7}" multicastport="${jboss.messaging.group.port:9876}"/>
<socket-binding name="modcluster" port="0" multicastaddress="224.0.1.105"
port="4712"/>
115

</socket-binding-groups>
The socket binding instances can be created and edited in the stand al o ne. xml and
d o mai n. 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 G eneral C o nfi g urati o n 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.
Report a bug
5.2.2. Configure Socket Bindings

Socket bindings can be defined in unique socket binding groups. A standalone server contains one
such group, the stand ard -so ckets 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.
T ab le 5.2. So cket B in d in g At t rib u t es
At t rib u t e
D escrip t io n
R o le
name
Logical name of the socket

configuration that should be
used elsewhere in the
configuration.
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.
Logical name of the interface to
which a socket based on this
configuration should be
bound. If not defined, the value
of the d efaul t-i nterface
attribute from the enclosing
socket binding group will be
used.
If the socket will be used for
multicast, the multicast address
to use.
Required
po rt
i nterface
mul ti cast-ad d ress
116
Required
Optional
Optional
At t rib u t e
D escrip t io n
R o le
mul ti cast-po rt
If the socket will be used for

multicast, the multicast port to
use.
If true, declares that the value
of po rt must always be used
for the socket and should not
be overridden by applying an
increment or decrement.
Optional
fi xed -po rt
Optional
C o n f ig u re So cket B in d in g s in So cket B in d in g G ro u p s
Choose either the Management CLI or the management console to configure your socket bindings
as required.
A. C o n f ig u re So cket B in d in g s U sin g t h e Man ag emen t C LI
Use the Management CLI to configure socket bindings.
a. Ad d a N ew So cket B in d in g
Use the ad d 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 po rt attribute declared
as 1234. The examples apply for both a standalone server and a managed domain
editing on the stand ard -so ckets socket binding group as shown.
[domain@ localhost:9999 /] /socket-binding-group=standardsockets/socket-binding=newsocket/:add(port=1234)
b. Ed it Pat t ern At t rib u t es
Use the wri te-attri bute 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 po rt value to 2020
[domain@ localhost:9999 /] /socket-binding-group=standardsockets/socket-binding=newsocket/:writeattribute(name=port,value=2020)
c. C o n f irm Pat t ern At t rib u t es
Confirm the values are changed by running the read -reso urce operation with the
i ncl ud e-runti me= true parameter to expose all current values active in the server
model.
[domain@ localhost:9999 /] /socket-binding-group=standardsockets/socket-binding=newsocket/:read-resource
B. C o n f ig u re So cket B in d in g s U sin g t h e Man ag emen t C o n so le
Use the management console to configure socket bindings.
117
Log into the management console of your managed domain or standalone server.
b. N avig at e t o t h e C o nfi g urati o n t ab .
Select the C o nfi g urati o n tab at the top of the screen.
c. Select t h e So cket Bi nd i ng it em f ro m t h e n avig at io n men u .
Expand the G eneral C o nfi g urati o n menu. Select So cket Bi nd i ng . If you are
using a managed domain, select the desired group in the So cket Bi nd i ng G ro ups
list.
d. Ad d a N ew So cket B in d in g
i. Click the Ad d button.
ii. Enter any required values for Name, P o rt and Bi nd i ng G ro up.
iii. Click Save to finish.
e. Ed it So cket B in d in g
i. Select a socket binding from the list and click Ed i t.
ii. Enter any required values such as Name, Interface or P o rt.
Report a bug
5.2.3. Net work Port s 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 80 80 , and your server uses a port offset of 10 0 , its
HTTP port is 8180 .
Unless otherwise stated, the ports use the TCP protocol.
T h e d ef au lt so cket b in d in g g ro u p s
ful l -ha-so ckets
ful l -so ckets
ha-so ckets
118
stand ard -so ckets

These socket binding groups are available only in d o mai n. xml . The standalone server profiles
contain only standard socket binding group. This group corresponds to standard-sockets in
stand al o ne. xml , ha-so ckets for stand al o ne-ha. xml , ful l -so ckets for stand al o neful l . xml , and ful l -ha-so ckets for stand al o ne-ful l -ha. xml . Standalone profiles contain
some more socket bindings, for example, management-{native,http,https}.
T ab le 5.3. R ef eren ce o f t h e d ef au lt so cket b in d in g s
N ame
Po rt
ajp
8009
http
8080
https
8443
jaco rb
3528
jaco rb
-ssl
jg ro up
sd i ag no
sti cs
3529
Mu lt ica
st Po rt
7500
45700
jg ro up
smpi ng
jg ro up
s-tcp
7600
jg ro up
s-tcpfd
jg ro up
s-ud p
57600
jg ro up
s-ud pfd
54200
55200
45688
D escrip t io n
f u ll- h aso cket s
f u llso cket s
h aso cket
st an d ar
dso cket
Apache JServ
Protocol. Used for
HTTP clustering
and load balancing.
The default port for
deployed web
applications.
SSL-encrypted
connection between
deployed web
applications and
clients.
CORBA services for
JTS transactions
and other ORBdependent services.
SSL-encrypted
CORBA services.
Multicast. Used for
peer discovery in HA
clusters. Not
configurable using
the Management
Interfaces.
Multicast. Used to
discover initial
membership in a HA
cluster.
Unicast peer
discovery in HA
clusters using TCP.
Used for HA failure
detection over TCP.
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
No
Yes
Yes
No
No
Yes
No
Yes
No
Yes
No
Yes
No
Yes
No
Yes
No
Yes
No
Yes
No
Multicast peer
discovery in HA
clusters using UD P.
Used for HA failure
detection over UD P.
Yes
No
Yes
No
Yes
No
Yes
No
119
N ame
Po rt
messag
i ng
messag
i ng g ro up
5445
messag
i ng thro ug
hput
mo d _cl
uster
5455
remo ti
4447
ng
txn4712
reco ver
yenvi ro
nment
txn4713
statusmanag e
r
Mu lt ica
st Po rt
23364
D escrip t io n
f u ll- h aso cket s
f u llso cket s
h aso cket
st an d ar
dso cket
JMS service.
Yes
Yes
No
No
Referenced by
HornetQ JMS
broadcast and
discovery groups.
Used by JMS
Remoting.
Yes
Yes
No
No
Yes
Yes
No
No
Multicast port for

communication
between JBoss EAP
6 and the HTTP
load balancer.
Used for remote EJB
invocation.
The JTA transaction
recovery manager.
Yes
No
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
The JTA / JTS

transaction
manager.
Yes
Yes
Yes
Yes
Man ag emen t Po rt s
In addition to the socket binding groups, each host controller opens two more ports for management
purposes:
9 9 9 0 - The Web Management Console port
9 9 9 9 - 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.
Report a bug
5.2.4 . About Port Offset s 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.
Report a bug
5.2.5. Configure Port Offset s
120
C o n f ig u re Po rt O f f set s
Choose either the Management CLI or the Management Console to configure your port offsets.
A. C o n f ig u re Po rt O f f set s U sin g t h e Man ag emen t C LI
Use the Management CLI to configure port offsets.
a. Ed it Po rt O f f set s
Use the wri te-attri bute operation to write a new value to the port offset atttribute.
The following example updates the so cket-bi nd i ng -po rt-o ffset value of servertwo 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=servertwo/:write-attribute(name=socket-binding-portoffset,value=250)
b. C o n f irm Po rt O f f set At t rib u t es
model.
[domain@ localhost:9999 /] /host=master/server-config=servertwo/:read-resource(include-runtime=true)
B. C o n f ig u re Po rt O f f set s U sin g t h e Man ag emen t C o n so le
Use the Management Console to configure port offsets.
Log into the Management Console of your Managed D omain.
b. Select t h e D o mai n t ab
Select the D o mai n tab at the top of the screen.
c. Ed it Po rt O f f set At t rib u t es
i. Select the server under the Avai l abl e Server C o nfi g urati o ns list and
click Ed i t at the top of the attibutes list below.
ii. Enter any desired values in the P o rt O ffset field.
Report a bug
5.3. IPv6
5.3.1. Configure JVM St ack Preferences for IPv6 Net working
121
Su mmary
This topic covers enabling IPv6 networking for the JBoss EAP 6 installation.
Pro ced u re 5.1. D isab le t h e IPv4 St ack Java Pro p ert y
1. Open the relevant file for the installation:
A. Fo r a St an d alo n e Server:
Open EAP_HOME/bi n/stand al o ne. co nf.
B. Fo r a Man ag ed D o main :
Open EAP_HOME/bi n/d o mai n. co nf.
2. Change the IPv4 Stack Java property to false:
-Djava.net.preferIPv4Stack=false
For example:
Examp le 5.8. JVM o p t io n s

# 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
Report a bug
5.3.2. Configure t he Int erface Declarat ions for IPv6 Net working
Su mmary
Follow these steps to configure the interface inet address to the IPv6 default:
Prereq u isit es
Pro ced u re 5.2. C o n f ig u re t h e In t erf ace f o r IPv6 N et wo rkin g
1. Select the C o nfi g urati o n tab at the top of the screen.
2. Expand the G eneral C o nfi g urati o n menu and select Interfaces.
122
3. Select the interface from the Avai l abl e Interfaces list.

4. Click Ed i t in the detail list.
5. Set the inet address to:
${jboss.bind.address.management:[ADDRESS]}
7. Restart the server to implement the changes.
Report a bug
5.3.3. Configure JVM St ack Preferences for IPv6 Addresses

Su mmary
This topic covers configuring the JBoss EAP 6 installation to prefer IPv6 addresses
through the configuration files.
Pro ced u re 5.3. C o n f ig u re t h e JB o ss EAP 6 In st allat io n t o Pref er IPv6 Ad d resses
1. Open the relevant file for the installation:
A. Fo r a St an d alo n e Server:
Open EAP_HOME/bi n/stand al o ne. co nf.
B. Fo r a Man ag ed D o main :
Open EAP_HOME/bi n/d o mai n. co nf.
2. Append the following Java property to the Java VM options:
-Djava.net.preferIPv6Addresses=true
For example:
Examp le 5.9 . JVM o p t io n s

#
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
Report a bug
123
5.4 . Remot ing

5.4 .1. Configurat ion of Message Siz e in Remot ing
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_INBO UND _MESSAG E_SIZE) and the
maximum outbound message size (MAX_O UT BO UND _MESSAG E_SIZE) to ensure that messages are
received and sent within appropriate size limits.
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_O UT BO UND _MESSAG E_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_INBO UND _MESSAG E_SIZE) the
message is closed asynchronously with the connection still open.
Report a bug
5.4 .2. Configure t he Remot ing Subsyst em

O verview
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.
Ad ap t in g t h e C LI C o mman d s
The CLI commands are formulated for a managed domain, when configuring the d efaul t profile. To
configure a different profile, substitute its name. For a standalone server, omit the
/pro fi l e= d efaul t part of the command.
C o n f ig u rat io n O u t sid e t h e R emo t in g Su b syst em
There are a few configuration aspects which are outside of the remo ti ng subsystem:
N et wo rk In t erf ace
124
The network interface used by the remo ti ng subsystem is the publ i c interface defined in
the d o mai n/co nfi g urati o n/d o mai n. xml or
stand al o ne/co nfi g urati o n/stand al o ne. xml .
<interfaces>
<interface name="management"/>
<interface name="public"/>
<interface name="unsecure"/>
</interfaces>
The per-host definition of the publ i c interface is defined in the ho st. xml in the same
directory as the d o mai n. xml or stand al o ne. xml . This interface is also used by several
other subsystems. Exercise caution when modifying it.
<interfaces>
<inet-address
value="${jboss.bind.address.management:127.0.0.1}"/>
</interface>
<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>
so cket - b in d in g
The default socket-binding used by the remo ti ng 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/
R emo t in g C o n n ect o r R ef eren ce f o r 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-poolname="default"/>
Secu re T ran sp o rt C o n f ig u rat io n

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
125
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.
Wo rker T h read Po o l
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 <wo rker-thread -po o l >, 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.
T ab le 5.4 . Wo rker T h read Po o l At t rib u t es
At t rib u t e
D escrip t io n
C LI C o mman d
read-threads
The number of read threads to

create for the remoting worker.
D efaults to 1.
write-threads
The number of write threads to

create for the remoting worker.
D efaults to 1.
task-keepalive
The number of milliseconds to

keep non-core remoting worker
task threads alive. D efaults to
60.
task-max-threads
The maximum number of

threads for the remoting worker
task thread pool. D efaults to
16 .
task-core-threads
The number of core threads for

the remoting worker task thread
pool. D efaults to 4 .
task-limit

remoting worker tasks to allow
before rejecting. D efaults to
16 384 .
/pro fi l e= d efaul t/subsys

tem= remo ti ng /: wri teattri bute(name= wo rkerread -thread s,val ue= 1)
tem= remo ti ng /: wri teattri bute(name= wo rkerwri te-thread s,val ue= 1)
tem= remo ti ng /: wri teattri bute(name= wo rkertaskkeepal i ve,val ue= 6 0 )
tem= remo ti ng /: wri teattri bute(name= wo rkertask-maxthread s,val ue= 16 )
tem= remo ti ng /: wri teattri bute(name= wo rkertask-co rethread s,val ue= 4 )
tem= remo ti ng /: wri teattri bute(name= wo rkertask-l i mi t,val ue= 16 384 )
C o n n ect o r
126
The connector is the main Remoting configuration element. Multiple connectors are allowed. Each
consists of a element <co nnecto r> 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.
T ab le 5.5. C o n n ect o r At t rib u t es
At t rib u t e
D escrip t io n
C LI C o mman d
socket-binding
The name of the socket binding

to use for this connector.
authentication-provider
The Java Authentication

Service Provider Interface for
Containers (JASPIC) module to
use with this connector. The
module must be in the
classpath.
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. Appl i cati o nR eal m is
available in a default JBoss
EAP 6 installation.

tem= remo ti ng /co nnecto r=
remo ti ng co nnecto r/: wri teattri bute(name= so cketbi nd i ng ,val ue= remo ti ng
)
remo ti ng co nnecto r/: wri teattri bute(name= authenti c
ati o npro vi d er,val ue= myP ro vi d
er)
remo ti ng co nnecto r/: wri teattri bute(name= securi tyreal m,val ue= Appl i cati o n
R eal m)
T ab le 5.6 . C o n n ect o r Elemen t s

At t rib u t e
D escrip t io n
C LI C o mman d
sasl
Enclosing element for Simple

Authentication and Security
Layer (SASL) authentication
mechanisms
Contains one or more
<pro perty> elements, each
with a name attribute and an
optional val ue attribute.
N/A
properties

remo ti ng co nnecto r/pro perty= myP r
o p/: ad d (val ue= myP ro pVa
l ue)
O u t b o u n d C o n n ect io n s
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.
127
Remote outbound connection connects to a remote resource and authenticates using a security
realm.
All of the outbound connections are enclosed in an <o utbo und -co nnecti o ns> element. Each of
these connection types takes an o utbo und -so cket-bi nd i ng -ref attribute. The outboundconnection takes a uri attribute. The remote outbound connection takes optional username and
securi ty-real m attributes to use for authorization.
T ab le 5.7. O u t b o u n d C o n n ect io n Elemen t s
At t rib u t e
D escrip t io n
outbound-connection
Generic outbound connection.
local-outbound-connection
remote-outbound-connection
C LI C o mman d

tem= remo ti ng /o utbo und co nnecti o n= myco nnecti o n/: ad d (uri = htt
p: //my-co nnecti o n)
Outbound connection with a
implicit local:// URI scheme.
tem= remo ti ng /l o cal o utbo und -co nnecti o n= myco nnecti o n/: ad d (o utbo un
d -so cket-bi nd i ng ref= remo ti ng 2)
Outbound connections for
remote:// URI scheme, using
tem= remo ti ng /remo tebasic/digest authentication with o utbo und -co nnecti o n= mya security realm.
co nnecti o n/: ad d (o utbo un
d -so cket-bi nd i ng ref= remo ti ng ,username= m
yUser,securi tyreal m= Appl i cati o nR eal m)
SASL Elemen t s
Before defining the SASL child elements, you need to create the initial SASL element. Use the
following command:
/profile=default/subsystem=remoting/connector=remotingconnector/security=sasl:add
The child elements of the SASL element are described in the table below.
T ab le 5.8. SASL ch ild elemen t s
At t rib u t e
128
D escrip t io n
C LI C o mman d
At t rib u t e
D escrip t io n
include-mechanisms
Contains a val ue attribute,

which is a list of SASL
mechanisms.
qop
strength
reuse-session
server-auth

which is a list of SASL Quality
of protection values, in
decreasing order of preference.

which is a list of SASL cipher
strength values, in decreasing
order of preference.
Contains a val ue attribute

which is a boolean value. If
true, attempt to reuse sessions.
Contains a val ue attribute

which is a boolean value. If
true, the server authenticates to
the client.
C LI C o mman d
/profile=default/subs
ystem=remoting/conne
ctor=remotingconnector/security=s
asl:writeattribute(name=inclu
de-mechanisms,value=
["DIGEST","PLAIN","G
SSAPI"])
asl:writeattribute(name=qop,v
alue=["auth"])
asl:writeattribute(name=stren
gth,value=
["medium"])
asl:writeattribute(name=reuse
-session,value=false)
asl:writeattribute(name=serve
r-auth,value=false)
policy
129
At t rib u t e
An
enclosing
D escrip
t io n element which
contains zero or more of the
following elements, which each
take a single val ue.
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 fal se
permits, and true denies.
no-anonymous whether
mechanisms that accept
anonymous login are
permitted. A value of fal se
permits, and true denies.
no-dictionary whether
mechanisms susceptible to
passive dictionary attacks
are allowed. A value of
fal se permits, and true
denies.
no-plain-text whether
mechanisms which are
susceptible to simple plain
passive attacks are allowed.
A value of fal se permits,
and true denies.
pass-credentials whether
mechanisms which pass
client credentials are
allowed.
C LI
C o mman d
asl/saslpolicy=policy:add
asl/saslpolicy=policy:writeattribute(name=forwa
rdsecrecy,value=true)
asl/saslpolicy=policy:writeattribute(name=noactive,value=false)
asl/saslpolicy=policy:writeattribute(name=noanonymous,value=fals
e)
asl/saslpolicy=policy:writeattribute(name=nodictionary,value=tru
e)
asl/sasl-
130
At t rib u t e
properties
D escrip t io n
Contains one or more

<pro perty> elements, each
with a name attribute and an
optional val ue attribute.
policy=policy:writeC LI
C o mman d
attribute(name=noplaintext,value=false)
asl/saslpolicy=policy:writeattribute(name=passcredentials,value=tr
ue)
asl/property=myprop:
add(value=1)
asl/property=myprop2
:add(value=2)
Examp le 5.10. Examp le C o n f ig u rat io n s

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-maxthreads="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" />
131
<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" outboundsocket-binding-ref="my-outbound-socket"/>
</outbound-connections>
</subsystem>
C o n f ig u rat io n Asp ect s N o t Yet D o cu men t ed

JND I and Multicast Automatic D etection
Report a bug
132
Chapt er 6 . Dat asource Management
Chapter 6. Datasource Management

6.1. Int roduct ion
6.1.1. About JDBC
The JD BC API is the standard that defines how databases are accessed by Java applications. An
application configures a datasource that references a JD BC 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 JD BC 4.0 specification is defined here: http://jcp.org/en/jsr/detail?id=221.
Pro ced u re 6 .1. T est d at aso u rce p o o ls co n n ect io n u sin g Man ag emen t C o n so le
1. Section 3.3.2, Log in to the Management Console .
2. Select the R u n t ime tab from the top of the Management Console.
3. Expand the Su b syst ems menu on the left, and select D at aso u rces.
4. Click the T est C o nnecti o n button to test the connection to the datasource and verify the
settings are correct.
Pro ced u re 6 .2. T est d at aso u rce co n n ect io n u sin g Man ag emen t C LI
1. Launch the CLI tool and connect to your server.
2. Run the following Management CLI command to test the connection:
A. In Standalone mode, enter the following command:
/subsystem=datasources/data-source=ExampleDS:test-connection-inpool
B. In D omain mode, enter the following command:
ho st= master/server= server-o ne/subsystem= d ataso urces/d ataso urce= Exampl eD S: test-co nnecti o n-i n-po o l
To get started with JD BC and datasources, refer to the JD BC D river section of the Administration and
Configuration Guide for JBoss EAP 6.
Report a bug
6.1.2. JBoss EAP 6 Support ed Dat abases

The list of JD BC compliant databases supported by JBoss EAP 6 is available here:
https://access.redhat.com/articles/111663.
Report a bug
6.1.3. T ypes of Dat asources
133
The two general types of resources are referred to as d ataso urces and XA d ataso urces.
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.
Report a bug
6.1.4 . T he Example Dat asource

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
D atabases .
Report a bug
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 *-d s. xml datasource configuration file was required in the deployment directory of the
server configuration. *-d s. 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 *-d s. xml files.
Report a bug
134
6.2. JDBC Drivers

6.2.1. Inst all a JDBC Driver wit h t he Management Console
Su mmary
Before your application can connect to a JD BC datasource, your datasource vendor's JD BC 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.
Prereq u isit es
Before performing this task, you need to meet the following prerequisites:
D ownload the JD BC driver from your database vendor.
Note
Any JD BC 4-compliant driver is automatically recognized and installed in the system by name
and version. A JD BC JAR is identified using the Java service provider mechanism. Such JARs
contain the META-INF/services/java.sql.D river text, which contains the name of the D river
classes in that JAR.
Pro ced u re 6 .3. Mo d if y t h e JD B C D river JAR

If the JD BC driver JAR is not JD BC 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.D river file, which contains one line indicating the fullyqualified class name of the JD BC 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. Section 3.3.2, Log in to the Management Console
7. 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 D eployed Application Using the Management
Console .
R esu lt :
The JD BC driver is deployed, and is available for your applications to use.
Report a bug
6.2.2. Inst all a JDBC Driver as a Core Module
135
6.2.2. Inst all a JDBC Driver as a Core Module

Prereq u isit es
Before performing this task, you need to meet the following prerequisites:
D ownload the JD BC driver from your database vendor. JD BC driver download locations are
listed here: Section 6.2.3, JD BC D river D ownload Locations .
Extract the archive.
Pro ced u re 6 .4 . In st all a JD B C D river as a C o re Mo d u le U sin g t h e Man ag emen t C LI
1. Start the Server.
2. Start the Management CLI, but do not use the --co nnect or -c argument to connect to the
running instance.
3. Use the mo d ul e ad d CLI command to add the new module.
Examp le 6 .1. Examp le C LI co mman d t o ad d a MySQ L JD B C d river mo d u le

module add --name=com.mysql --resources=/path/to/mysql.jar -dependencies=javax.api,javax.transaction.api
Note
The mo d ul e ad d CLI command performs the following steps, which could instead be
completed manually if desired:
a. A file path structure will be created under the
EAP_HOME/mo d ul es/system/l ayers/base directory. For example, for a
MySQL JD BC driver, the following will be created:
EAP_HOME/mo d ul es/system/l ayers/base/co m/mysq l /mai n/.
b. The JAR files specified as resources will be copied to the mai n/ subdirectory.
c. A module.xml file with the specified dependencies will be created in the mai n/
subdirectory. See Section 7.1.1, Modules for an example of a module.xml file.
Execute mo d ul e --hel p for more details on using this command to add and remove
modules.
4. Use the co nnect CLI command to connect to the running instance.
5. Run the CLI command to add the JD BC driver module to the server configuration.
The command you choose depends on the number of classes listed in the /MET AINF/servi ces/java. sq l . D ri ver file located in the JD BC driver JAR. For example, the
/MET A-INF/servi ces/java. sq l . D ri ver file in the MySQL 5.1.20 JD BC JAR lists two
classes:
co m. mysq l . jd bc. D ri ver
co m. mysq l . fabri c. jd bc. Fabri cMySQ LD ri ver
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:
136
Examp le 6 .2. D river class erro r

JBAS014749: Operation handler failed: Service jboss.jdbcdriver.mysql is already registered
A. Run the CLI command for JD BC JARs containing one class entry.
/subsystem=datasources/jdbc-driver=DRIVER_NAME:add(drivername=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xadatasource-class-name=XA_DATASOURCE_CLASS_NAME)
Examp le 6 .3. C LI C o mman d f o r St an d alo n e Mo d e f o r JD B C JAR s wit h o n e

d river class
/subsystem=datasources/jdbc-driver=mysql:add(drivername=mysql,driver-module-name=com.mysql,driver-xa-datasourceclass-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)
Examp le 6 .4 . C LI C o mman d f o r D o main Mo d e f o r JD B C JAR s wit h o n e d river

class
/profile=ha/subsystem=datasources/jdbc-driver=mysql:add(drivername=mysql,driver-module-name=com.mysql,driver-xa-datasourceclass-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)
B. Run the CLI command for JD BC JARs containing multiple class entries.
/subsystem=datasources/jdbc-driver=DRIVER_NAME:add(drivername=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xadatasource-class-name=XA_DATASOURCE_CLASS_NAME, driver-classname=DRIVER_CLASS_NAME)
Examp le 6 .5. C LI C o mman d f o r St an d alo n e Mo d e f o r JD B C JAR s wit h

mu lt ip le d river class en t ries
/subsystem=datasources/jdbc-driver=mysql:add(drivername=mysql,driver-module-name=com.mysql,driver-xa-datasourceclass-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource,
driver-class-name=com.mysql.jdbc.Driver)
Examp le 6 .6 . C LI C o mman d f o r D o main Mo d e f o r JD B C JAR s wit h mu lt ip le

d river class en t ries
/profile=ha/subsystem=datasources/jdbc-driver=mysql:add(drivername=mysql,driver-module-name=com.mysql,driver-xa-datasourceclass-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource,
driver-class-name=com.mysql.jdbc.Driver)
137
Examp le 6 .7. C LI C o mman d f o r D o main Mo d e f o r JD B C JAR s wit h mu lt ip le

/profile=ha/subsystem=datasources/jdbcdriver=oracle/:add(driver-module-name=com.oracle,drivername=oracle,jdbc-compliant=true,driver-datasource-classname=oracle.jdbc.OracleDriver)
R esu lt
The JD BC driver is now installed and set up as a core module, and is available to be referenced by
application datasources.
Report a bug
6.2.3. JDBC Driver Download Locat ions

The following table gives the standard download locations for JD BC 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.
T ab le 6 .1. JD B C d river d o wn lo ad lo cat io n s

Ven d o r
D o wn lo ad Lo cat io n
MySQL
PostgreSQL
Oracle
http://www.mysql.com/products/connector/
http://jdbc.postgresql.org/
http://www.oracle.com/technetwork/database/feat
ures/jdbc/index-091264.html
http://www-306.ibm.com/software/data/db2/java/
http://www.sybase.com/products/allproductsaz/softwaredeveloperkit/jconnect
http://msdn.microsoft.com/data/jdbc/
IBM
Sybase
Microsoft
Report a bug
6.2.4 . Access Vendor Specific Classes

Su mmary
This topic covers the steps required to use the JD BC specific classes. This is necessary when an
application needs to use vendor specific functionality that is not part of the JD BC API.
138
Warning
This is advanced usage. Only applications that need functionality not found in the JD BC 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.
Prereq u isit es
Section 6.2.2, Install a JD BC D river as a Core Module .
Pro ced u re 6 .5. Ad d a D ep en d en cy t o t h e Ap p licat io n
You can add a dependency to an application using either of the following methods. Choose
whichever method you prefer.
A. C o n f ig u re t h e MANIFEST . MF f ile
a. Open the application's MET A-INF/MANIFEST . MF file in a text editor.
b. Add a dependency for the JD BC module and save the file.
Dependencies: MODULE_NAME
Examp le 6 .8. MAN IFEST .MF f ile wit h co m.mysq l d eclared as a d ep en d en cy

Dependencies: com.mysql
B.
a. C reat e a jbo ss-d epl o yment-structure. xml f ile

Create a file called jbo ss-d epl o yment-structure. xml in the MET A-INF/ or WEBINF folder of the application.
Examp le 6 .9 . jbo ss-d epl o yment-structure. xml f ile wit h co m.mysq l

d eclared as a d ep en d en cy
<jboss-deployment-structure>
139
<deployment>
<dependencies>
<module name="com.mysql" />
</dependencies>
</deployment>
</jboss-deployment-structure>
Examp le 6 .10. Access t h e Ven d o r Sp ecif ic 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();
Report a bug
6.3. Non-XA Dat asources

6.3.1. Creat e a Non-XA Dat asource wit h t he Management Int erfaces
Su mmary
This topic covers the steps required to create a non-XA datasource, using either the Management
Console or the Management CLI.
Prereq u isit es
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 JD BC drivers that are installed as modules and correctly referenced from
profiles are detectable while creating a datasource using the Management Console in domain
mode.
14 0
Pro ced u re 6 .6 . C reat e a D at aso u rce u sin g eit h er t h e Man ag emen t C LI o r t h e

Man ag emen t C o n so le
A. Man ag emen t C LI
a. Launch the CLI tool and connect to your server.
b. 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
/MET A-INF/servi ces/java. sq l . D ri ver file located in the JD BC 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
mysq l -co nnecto r-java-5. 1. 31bi n. jarco m. mysq l . jd bc. D ri ver_5_1.
data-source add --name=DATASOURCE_NAME --jndi-name=JNDI_NAME -driver-name=DRIVER_NAME --connection-url=CONNECTION_URL

c. Enable the datasource:
data-source enable --name=DATASOURCE_NAME
B. Man ag emen t C o n so le
a. Login to the Management Console.
b. N avig at e t o t h e D ataso urces p an el in t h e Man ag emen t C o n so le
i. Select the C o nfi g urati o n tab from the top of the console.
ii. For D omain mode only, select a profile from the drop-down box in the top left.
iii. Expand the Su b syst ems menu on the left of the console, then expand the
C o n n ect o r menu.
iv. Select D at aso u rces from the menu on the left of the console.
c. C reat e a n ew d at aso u rce
i. Click Ad d at the top of the D ataso urces panel.
ii. Enter the new datasource attributes in the C reate D ataso urce wizard and
proceed with the Next button.
14 1
iii. Enter the JD BC driver details in the C reate D ataso urce wizard and click
Next to continue.
iv. Enter the connection settings in the C reate D ataso urce wizard.
v. Click the T est C o nnecti o n button to test the connection to the datasource
and verify the settings are correct.
vi. Click D o ne to finish
R esu lt
The non-XA datasource has been added to the server. It is now visible in either the
stand al o ne. xml or d o mai n. xml file, as well as the management interfaces.
Report a bug
6.3.2. Modify a Non-XA Dat asource wit h t he Management Int erfaces

Su mmary
This topic covers the steps required to modify a non-XA datasource, using either the Management
Prereq u isit es
Section 2.2.1, Start JBoss EAP 6 .
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.
Pro ced u re 6 .7. Mo d if y a N o n - XA D at aso u rce

a. Section 3.4.2, Launch the Management CLI .
b. Use the wri te-attri bute command to configure a datasource attribute:
/subsystem=datasources/data-source=DATASOURCE_NAME:writeattribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)
c. Reload the server to confirm the changes:
reload
a. Section 3.3.2, Log in to the Management Console .
14 2
iv. Select D at aso u rces from expanded menu.
c. Ed it t h e d at aso u rce
i. Select a datasource from the Avai l abl e D ataso urces list. The datasource
attributes are displayed below.
ii. Click Ed i t to edit the datasource attributes.
R esu lt
The non-XA datasource has been configured. The changes are now visible in either the
To create a new datasource, refer here: Section 6.3.1, Create a Non-XA D atasource with the
Management Interfaces .
To remove the datasource, refer here: Section 6.3.3, Remove a Non-XA D atasource with the
Report a bug
6.3.3. Remove a Non-XA Dat asource wit h t he Management Int erfaces

Su mmary
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.
Prereq u isit es
Pro ced u re 6 .8. R emo ve a N o n - XA D at aso u rce
b. Run the following command to remove a non-XA datasource:
data-source remove --name=DATASOURCE_NAME
14 3
iv. Select D at aso u rces.
c. Select the datasource to be deleted, then click R emo ve.
R esu lt
The non-XA datasource has been removed from the server.
To add a new datasource, refer here: Section 6.3.1, Create a Non-XA D atasource with the
Report a bug
6.4 . XA Dat asources

6.4 .1. Creat e an XA Dat asource wit h t he Management Int erfaces
Prereq u isit es:
Su mmary
This topic covers the steps required to create an XA datasource, using either the Management
Note
Pro ced u re 6 .9 . C reat e an XA D at aso u rce, U sin g Eit h er t h e Man ag emen t C LI o r t h e

b. Run the following Management CLI command to create an XA datasource, configuring
the variables as appropriate:
14 4
Note
The value for DRIVER_NAME depends on the number of classes listed in the
/MET A-INF/servi ces/java. sq l . D ri ver file located in the JD BC 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
mysq l -co nnecto r-java-5. 1. 31bi n. jarco m. mysq l . jd bc. D ri ver_5_1.
xa-data-source add --name=XA_DATASOURCE_NAME --jndiname=JNDI_NAME --driver-name=DRIVER_NAME --xa-datasourceclass=XA_DATASOURCE_CLASS

c. C o n f ig u re t h e XA d at aso u rce p ro p ert ies
i. Set t h e server n ame
Run the following command to configure the server name for the host:
/subsystem=datasources/xa-datasource=XA_DATASOURCE_NAME/xa-datasourceproperties=ServerName:add(value=HOSTNAME)
ii. Set t h e d at ab ase n ame
Run the following command to configure the database name:
/subsystem=datasources/xa-datasource=XA_DATASOURCE_NAME/xa-datasourceproperties=DatabaseName:add(value=DATABASE_NAME)
d. Enable the datasource:
xa-data-source enable --name=XA_DATASOURCE_NAME
ii. For D omain mode only, select a profile from the drop-down box at the top left.
14 5
c. Select the XA D ataso urce tab.
d. C reat e a n ew XA d at aso u rce
i. Click Ad d .
ii. Enter the new XA datasource attributes in the C reate XA D ataso urce wizard
and click Next.
iii. Enter the JD BC driver details in the C reate XA D ataso urce wizard and click
Next.
iv. Enter the XA properties and click Next.
v. Enter the connection settings in the C reate XA D ataso urce wizard.
vi. Click the T est C o nnecti o n button to test the connection to the XA
datasource and verify the settings are correct.
vii. Click D o ne to finish
R esu lt
The XA datasource has been added to the server. It is now visible in either the stand al o ne. xml or
d o mai n. xml file, as well as the management interfaces.
See Also :
Section 6.4.2, Modify an XA D atasource with the Management Interfaces
Section 6.4.3, Remove an XA D atasource with the Management Interfaces
Report a bug
6.4 .2. Modify an XA Dat asource wit h t he Management Int erfaces

Su mmary
This topic covers the steps required to modify an XA datasource, using either the Management
Prereq u isit es
Pro ced u re 6 .10. Mo d if y an XA D at aso u rce, U sin g Eit h er t h e Man ag emen t C LI o r t h e
b. C o n f ig u re XA d at aso u rce at t rib u t es
14 6
Use the wri te-attri bute command to configure a datasource attribute:

/subsystem=datasources/xa-datasource=XA_DATASOURCE_NAME:writeattribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)
c. C o n f ig u re XA d at aso u rce p ro p ert ies
Run the following command to configure an XA datasource subresource:
/subsystem=datasources/xa-data-source=DATASOURCE_NAME/xadatasource-properties=PROPERTY_NAME:add(value=PROPERTY_VALUE)
d. Reload the server to confirm the changes:
reload
ii. For D omain Mode only, select a profile from the drop-down box at top left.
d. Ed it t h e d at aso u rce
i. Select the relevant XA datasource from the Avai l abl e XA D ataso urces list.
The XA datasource attributes are displayed in the Attri butes panel below it.
ii. Select the Ed i t button to edit the datasource attributes.
iii. Edit the XA datasource attributes and select the Save button when done.
R esu lt
The XA datasource has been configured. The changes are now visible in either the
To create a new datasource, refer here: Section 6.4.1, Create an XA D atasource with the
To remove the datasource, refer here: Section 6.4.3, Remove an XA D atasource with the
Report a bug
6.4 .3. Remove an XA Dat asource wit h t he Management Int erfaces
14 7
6.4 .3. Remove an XA Dat asource wit h t he Management Int erfaces

Su mmary
This topic covers the steps required to remove an XA datasource from JBoss EAP 6, using either the
Management Console or the Management CLI.
Prereq u isit es
Pro ced u re 6 .11. R emo ve an XA D at aso u rce U sin g Eit h er t h e Man ag emen t C LI o r t h e
b. Run the following command to remove an XA datasource:
xa-data-source remove --name=XA_DATASOURCE_NAME
d. Select the registered XA datasource to be deleted, and click R emo ve to permanently
delete the XA datasource.
R esu lt
The XA datasource has been removed from the server.
To add a new XA datasource, refer here: Section 6.4.1, Create an XA D atasource with the
Report a bug
6.4 .4 . XA Recovery
6 .4 .4 .1 . Abo ut XA Re co ve ry Mo dule s
Each XA resource needs a recovery module associated with its configuration. The recovery module
must extend class co m. arjuna. ats. jta. reco very. XAR eso urceR eco very.
14 8
JBoss EAP 6 provides recovery modules for JD BC 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.
Report a bug
6 .4 .4 .2 . Co nfigure XA Re co ve ry Mo dule s
For most JD BC 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 JD BC 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 D atasource with the Management Interfaces and
Section 6.4.2, Modify an XA D atasource 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.
T ab le 6 .2. G en eral C o n f ig u rat io n At t rib u t es
At t rib u t e
D escrip t io n
recovery-username
The username the recovery module should use to connect to the

resource for recovery.
The password the recovery module should use to connect to the
resource for recovery.
The security domain the recovery module should use to connect
to the resource for recovery.
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
co m. arjuna. ats. jta. reco very. XAR eso urceR eco very.
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.
recovery-password
recovery-security-domain
recovery-plugin-class-name
recovery-plugin-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.
Ven d o r- Sp ecif ic C o n f ig u rat io n In f o rmat io n

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.
O racle
14 9
If the Oracle datasource is configured incorrectly, you may see errors like the following in
your log output:
Examp le 6 .11. In co rrect co n f ig u rat io n erro r

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.
Examp le 6 .12. G ran t co n f ig u rat io n

GRANT SELECT ON sys.dba_pending_transactions TO recoveryusername;
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 EXEC UT E statement to the
following:
GRANT EXECUTE ON sys.dbms_system TO recovery-username;
Po st g reSQ L an d Po st g res Plu s Ad van ced Server
For PostgreSQL to be able to handle XA transaction, change the configuration parameter
max_prepared_transactions to an value higher than 0.
MySQ L
No special configuration is required. For more information, refer to MySQL documentation.
IB M D B 2
No special configuration is required. For more information, refer to IBM D B2
documentation.
Syb ase
Sybase expects XA transactions to be enabled on the database. Without correct database
configuration, XA transactions will not work. enabl e xact co o rd i nati o n 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
.
150
MSSQ L
For more information, refer to Microsoft documentation. You can also refer
http://msdn.microsoft.com/en-us/library/aa342335.aspx as a starting point.
Ven d o r- sp ecif ic issu es an d t h eir co n seq u en ces
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.
O racle
There are no known issues related to database.
Po st g reSQ L
Jdbc driver returns XAER_RMERR when an error occurs during the call of commit
method protocol. D atabase returns this error code and leaves the transaction in i nd o ubt 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 Heuri sti c 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
Po st g res Plu s Ad van ced Server
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 XAR eso urce. ro l l back is called for the same XID more than once then
XAExcepti o n is thrown. Calling rollback against the same XID several times is
compliant with JTS spec and no XAExcepti o n should be thrown. For more information,
see https://github.com/pgjdbc/pgjdbc/issues/78.
MySQ L
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.
IB M D B 2
There are no known issues related to database.
Syb ase
151

MSSQ L
This issue was reported on the Microsoft Connect site at
https://connect.microsoft.com/SQLServer/feedback/details/1207381/jdbc-driver-is-notxa-compliant-in-case-of-connection-failure-error-code-xaer-rmerr-is-returned-insteadof-xaer-rmretry.
The call of XAR eso urce. ro l l back for the same XID causes the following message
being logged in server log file.
WARN [com.arjuna.ats.jtax] ...: XAResourceRecord.rollback
caused an error from resource ... in transaction ...:
java.lang.NullPointerException
Messag in g
IB M Web sp h ere
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.'
Act iveMQ
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 i nd o ubt state on message broker side. This behaviour is against XA specification and the
152
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 .
caused an XA error: ARJUNA016099: Unknown error code:0 from
resource ... in transaction ...:
javax.transaction.xa.XAException: Transaction ... has not been
started.
T IB C O
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.
caused an XA error: XAException.XAER_RMFAIL from resource ...
in transaction ...: javax.transaction.xa.XAException
Report a bug
6.5. Dat asource Securit y

6.5.1. About Dat asource Securit y
D atasource 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.
Examp le 6 .13. Secu rit y D o main Examp le

<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 D sRealm 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>
153
<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 no ne or by removing the attribute altogether. However, if caching is desired, then a
separate security domain should be used for each datasource.
Examp le 6 .14 . Passwo rd Vau lt Examp le

<security>
<user-name>admin</user-name>
<password>${VAULT::ds_ExampleDS::password::N2NhZDYzOTMtNWE0OS00ZGQ0LWE4
MmEtMWNlMDMyNDdmNmI2TElORV9CUkVBS3ZhdWx0}</password>
</security>
Report a bug
6.6. Dat abase Connect ion Validat ion

6.6.1. Configure Dat abase Connect ion Validat ion Set t ings
O verview
D atabase 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
<val i d ati o n> element within the <d ataso urce> section of the server configuration file. Follow the
steps below to configure the datasource settings to enable database connection validation in JBoss
EAP 6.
Pro ced u re 6 .12. C o n f ig u re D at ab ase C o n n ect io n Valid at io n Set t in g s
1. C h o o se a Valid at io n Met h o d
Select one of the following validation methods.
A. <valid at e- o n - mat ch >t ru e</valid at e- o n - mat ch >
When the <val i d ate-o n-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.
154
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-fastfai l > 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.
B. <b ackg ro u n d - valid at io n >t ru e</b ackg ro u n d - valid at io n >
When the <backg ro und -val i d ati o n> option is set to true, it is used in combination
with the <backg ro und -val i d ati o n-mi l l i s> value to determine how often
background validation runs. The default value for the <backg ro und -val i d ati o nmi l l i s> parameter is 0 milliseconds, meaning it is disabled by default. This value
should not be set to the same value as your <i d l e-ti meo ut-mi nutes> setting.
It is a balancing act to determine the optimum <backg ro und -val i d ati o n-mi l l i s>
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 <val i d ate-o n-match> option is set to true, the <backg ro und val i d ati o n> option should be set to fal se. The reverse is also true. If the
<backg ro und -val i d ati o n> option is set to true, the <val i d ate-o n-match>
option should be set to fal se.
2. C h o o se a Valid at io n Mech an ism

Select one of the following validation mechanisms.
A. Sp ecif y a <valid - co n n ect io n - ch ecker> C lass N ame
This is the preferred mechanism as it optimized for the particular RD BMS in use. JBoss
EAP 6 provides the following connection checkers:
org.jboss.jca.adapters.jdbc.extensions.db2.D B2ValidConnectionChecker
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.JD BC4ValidConnectionChecker
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
155
B. Sp ecif y SQ L f o r <ch eck- valid - co n n ect io n - sq l>

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-validconnection-sql>
For MySQL or PostgreSQL, you might specify the following SQL statement:
<check-valid-connection-sql>select 1</check-valid-connection-sql>
3. Set t h e <excep t io n - so rt er> C lass N ame
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.D B2ExceptionSorter
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
Report a bug
6.7. Dat asource Configurat ion

6.7.1. Dat asource Paramet ers
T ab le 6 .3. D at aso u rce p aramet ers co mmo n t o n o n - XA an d XA d at aso u rces
Paramet er
D escrip t io n
jndi-name
pool-name
The unique JND I name for the datasource.

The name of the management pool for the
datasource.
Whether or not the datasource is enabled.
Whether to bind the datasource to global JND I.
enabled
use-java-context
156
Paramet er
D escrip t io n
spy
Enable spy functionality on the JD BC layer.

This logs all JD BC traffic to the datasource.
Note that the logging category
jbo ss. jd bc. spy must also be set to the log
level D EBUG in the logging subsystem.
Enable the cached connection manager.
A SQL statement which executes when the
connection is added to the connection pool.
One of the following:
use-ccm
new-connection-sql
transaction-isolation
TRANSACTION_READ _UNCOMMITTED
TRANSACTION_READ _COMMITTED
TRANSACTION_REPEATABLE_READ
TRANSACTION_SERIALIZ ABLE
TRANSACTION_NONE
url-selector-strategy-class-name
security
validation
timeout
statement
A class that implements interface

o rg . jbo ss. jca. ad apters. jd bc. UR LSel e
cto rStrateg y.
Contains child elements which are security
settings. See Table 6.8, Security parameters .
Contains child elements which are validation
settings. See Table 6.9, Validation parameters .
Contains child elements which are timeout
settings. See Table 6.10, Timeout parameters .
Contains child elements which are statement
settings. See Table 6.11, Statement
parameters .
T ab le 6 .4 . N o n - XA d at aso u rce p aramet ers

Paramet er
D escrip t io n
jta
Enable JTA integration for non-XA datasources.

D oes not apply to XA datasources.
The JD BC driver connection URL.
The fully-qualified name of the JD BC driver
class.
Arbitrary connection properties passed to the
method D ri ver. co nnect(url ,pro ps). Each
connection-property specifies a string
name/value pair. The property name comes from
the name, and the value comes from the element
content.
Contains child elements which are pooling
settings. See Table 6.6, Pool parameters
common to non-XA and XA datasources .
The delimiter for URLs in a connection-url for
High Availability (HA) clustered databases.
connection-url
driver-class
connection-property
pool
url-delimiter
T ab le 6 .5. XA d at aso u rce p aramet ers
157
Paramet er
D escrip t io n
xa-datasource-property
A property to assign to implementation class

XAD ataSo urce. 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).
The fully-qualified name of the implementation
class javax. sq l . XAD ataSo urce.
A unique reference to the class loader module
which contains the JD BC driver. The accepted
format is driverName#majorVersion.minorVersion.
Contains child elements which are pooling
settings. See Table 6.6, Pool parameters
common to non-XA and XA datasources and
Table 6.7, XA pool parameters .
Contains child elements which are recovery
settings. See Table 6.12, Recovery
parameters .
xa-datasource-class
driver
xa-pool
recovery
T ab le 6 .6 . Po o l p aramet ers co mmo n t o n o n - XA an d XA d at aso u rces

Paramet er
D escrip t io n
min-pool-size
The minimum number of connections a pool

holds.
The maximum number of connections a pool
can hold.
Whether to try to prefill the connection pool. The
default is fal se.
Whether the idle connection scan should strictly
stop marking for closure of any further
connections, once the mi n-po o l -si ze has
been reached. The default value is fal se.
Whether the pool is flushed in the case of an
error. Valid values are:
max-pool-size
prefill
use-strict-min
flush-strategy
FailingConnectionOnly
IdleConnections
EntirePool
The default is Fai l i ng C o nnecti o nO nl y.
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.
T ab le 6 .7. XA p o o l p aramet ers

Paramet er
D escrip t io n
is-same-rm-override
Whether the
javax. transacti o n. xa. XAR eso urce. i sS
ameR M(XAR eso urce) class returns true or
fal se.
158
Paramet er
D escrip t io n
interleaving
Whether to enable interleaving for XA

connection factories.
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.
no-tx-separate-pools
Using this option will cause your total pool size

to be twice max-po o l -si ze, because two
actual pools will be created.
pad-xid
wrap-xa-resource
Whether to pad the Xid.

Whether to wrap the XAResource in an
o rg . jbo ss. tm. XAR eso urceWrapper
instance.
T ab le 6 .8. Secu rit y p aramet ers

Paramet er
D escrip t io n
user-name
The username to use to create a new

connection.
The password to use to create a new
connection.
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.
D efines a reauthentication plug-in to use to
reauthenticate physical connections.
password
security-domain
reauth-plugin
T ab le 6 .9 . Valid at io n p aramet ers

Paramet er
D escrip t io n
valid-connection-checker
An implementation of interface
o rg . jbo ss. jca. ad apto rs. jd bc. Val i d C
o nnecti o nC hecker which provides a
SQ LExcepti o n. i sVal i d C o nnecti o n(C o n
necti o n e) method to validate a connection.
An exception means the connection is
destroyed. This overrides the parameter checkval i d -co nnecti o n-sq l if it is present.
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.
check-valid-connection-sql
159
Paramet er
D escrip t io n
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 val i d ate-o n-match is
typically not done in conjunction with specifying
" true" for backg ro und -val i d ati o n.
Val i d ate-o n-match is needed when a client
must have a connection validated prior to use.
This parameter is false by default.
background-validation
background-validation-millis
use-fast-fail
stale-connection-checker
exception-sorter
Specifies that connections are validated on a

background thread. Background validation is a
performance optimization when not used with
val i d ate-o n-match. If val i d ate-o nmatch is true, using backg ro und val i d ati o n 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.
The amount of time, in milliseconds, that
background validation runs.
If true, fail a connection allocation on the first
attempt, if the connection is invalid. D efaults to
fal se.
An instance of
o rg . jbo ss. jca. ad apters. jd bc. Stal eC o
nnecti o nC hecker which provides a Boolean
i sStal eC o nnecti o n(SQ LExcepti o n e)
method. If this method returns true, the
exception is wrapped in an
o rg . jbo ss. jca. ad apters. jd bc. Stal eC o
nnecti o nExcepti o n, which is a subclass of
SQ LExcepti o n.
An instance of
o rg . jbo ss. jca. ad apters. jd bc. Excepti
o nSo rter which provides a Boolean
i sExcepti o nFatal (SQ LExcepti o n e)
method. This method validates whether an
exception is broadcast to all instances of
javax. reso urce. spi . C o nnecti o nEventL
i stener as a co nnecti o nErro rO ccurred
message.
T ab le 6 .10. T imeo u t p aramet ers

Paramet er
160
D escrip t io n
Paramet er
D escrip t io n
use-try-lock
Uses tryLo ck() instead of l o ck(). This

attempts to obtain the lock for the configured
number of seconds, before timing out, rather
than failing immediately if the lock is
unavailable. D efaults to 6 0 seconds. As an
example, to set a timeout of 5 minutes, set <usetry-l o ck>300</use-try-l o ck>.
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. D efaults to
30000, which is 30 seconds.
The maximum time, in minutes, before an idle
connection is closed. The actual maximum time
depends upon the idleRemover scan time, which
is half of the smallest i d l e-ti meo utmi nutes of any pool.
Whether to set the query timeout based on the
time remaining until transaction timeout. Any
configured query timeout is used if no
transaction exists. D efaults to fal se.
Timeout for queries, in seconds. The default is
no timeout.
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.
How long, in milliseconds, to wait before retrying
to allocate a connection. The default is 5000,
which is 5 seconds.
If non-zero, this value is passed to method
XAR eso urce. setT ransacti o nT i meo ut.
blocking-timeout-millis
idle-timeout-minutes
set-tx-query-timeout
query-timeout
allocation-retry
allocation-retry-wait-millis
xa-resource-timeout
T ab le 6 .11. St at emen t p aramet ers

Paramet er
D escrip t io n
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 valu es
true: statements and result sets are tracked,
and a warning is issued if they are not
closed.
fal se: neither statements or result sets are
tracked.
no warn: statements are tracked but no
warning is issued. This is the default.
161
Paramet er
D escrip t io n
prepared-statement-cache-size
The number of prepared statements per

connection, in a Least Recently Used (LRU)
cache.
Whether asking for the same statement twice
without closing it uses the same underlying
prepared statement. The default is fal se.
share-prepared-statements
T ab le 6 .12. R eco very p aramet ers

Paramet er
D escrip t io n
recover-credential
A username/password pair or security domain to

use for recovery.
An implementation of the
o rg . jbo ss. jca. co re. spi . reco veryR eco
veryP l ug i n class, to be used for recovery.
recover-plugin
Report a bug
6.7.2. Dat asource Connect ion URLs

T ab le 6 .13. D at aso u rce C o n n ect io n U R Ls
D at aso u rce
C o n n ect io n U R L
PostgreSQL
jdbc:postgresql://SERVER_NAME:PORT/DATABA
SE_NAME
jdbc:mysql://SERVER_NAME:PORT/DATABASE_N
AME
jdbc:oracle:thin:@ORACLE_HOST:PORT:ORACL
E_SID
jdbc:db2://SERVER_NAME:PORT/DATABASE_NA
ME
jdbc:sqlserver://SERVER_NAME:PORT;D atabase
Name=DATABASE_NAME
MySQL
Oracle
IBM D B2
Microsoft SQLServer
Note
The
jdbc:microsoft:sqlserver://SERVER_NAME:
PORT;D atabaseName=DATABASE_NAME
template does not work with new
database.
Report a bug
6.7.3. Dat asource Ext ensions

D atasource deployments can use several extensions in the JD BC resource adapter to improve the
connection validation, and check whether an exception should reestablish the connection. Those
extensions are:
162
T ab le 6 .14 . D at aso u rce Ext en sio n s

D at aso u rce Ext en sio n
C o n f ig u rat io n Paramet er
D escrip t io n
org.jboss.jca.adapters.jdbc.spi
.ExceptionSorter
<exception-sorter>
.StaleConnectionChecker
<stale-connection-checker>
.ValidConnection
<valid-connection-checker>
Checks whether an
SQLException is fatal for the
connection on which it was
thrown
Wraps stale SQLExceptions in
a
o rg . jbo ss. jca. ad apters.
jd bc. Stal eC o nnecti o nExc
epti o n
Checks whether a connection
is valid for use by the
application
JBoss EAP 6 also features implementations of these extensions for several supported databases.
Ext en sio n Imp lemen t at io n s
G en eric
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.JD BC4ValidConnectionChecker
Po st g reSQ L
org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
MySQ L
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
IB M D B 2
org.jboss.jca.adapters.jdbc.extensions.db2.D B2ExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.db2.D B2StaleConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.db2.D B2ValidConnectionChecker
Syb ase
org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
Micro so f t SQ LServer
163
O racle
org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker
org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
Report a bug
6.7.4 . View Dat asource St at ist ics

You can view statistics from defined datasources for both the jd bc and po o l using appropriately
modified versions of the commands below:
Examp le 6 .15. C LI f o r d o main mo d e:

Change /ho st= master/server= server-o ne and d ata-so urce= Exampl eD S according to
the environment.
[domain@ localhost:9999 /] /host=master/server=serverone/subsystem=datasources/data-source=ExampleDS/statistics=pool:readresource(include-runtime=true)
{
"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"
}
}
Examp le 6 .16 . C LI f o r st an d alo n e mo d e:

Change d ata-so urce= Exampl eD S according to the environment.
[standalone@ localhost:9999 /] /subsystem=datasources/datasource=ExampleDS/statistics=pool:read-resource(include-runtime=true)
{
"result" => {
"ActiveCount" => "0",
164
"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 fal se.
Report a bug
6.7.5. Dat asource St at ist ics

C o re St at ist ics
The following table contains a list of the supported datasource core statistics:
T ab le 6 .15. C o re St at ist ics
N ame
D escrip t io n
Acti veC o unt
The number of active connections. Each of the connections is either in

use by an application or available in the pool
The number of available connections in the pool.
The average time spent blocking on obtaining an exclusive lock on the
pool. The value is in milliseconds.
The average time spent creating a connection. The value is in
milliseconds.
The number of connections created.
The number of connections destroyed.
The number of connections currently in use.
The maximum time it took to create a connection. The value is in
milliseconds.
The maximum number of connections used.
The maximum number of requests waiting for a connection at the same
time.
The maximum time spent waiting for an exclusive lock on the pool.
The number of timed out connections.
The total time spent waiting for an exclusive lock on the pool. The value is
in milliseconds.
Avai l abl eC o unt

Averag eBl o cki ng T
i me
Averag eC reati o nT i
me
C reated C o unt
D estro yed C o unt
InUseC o unt
MaxC reati o nT i me
MaxUsed C o unt
MaxWai tC o unt
MaxWai tT i me
T i med O ut
T o tal Bl o cki ng T i m
e
165
N ame
D escrip t io n
T o tal C reati o nT i m
e
The total time spent creating connections. The value is in milliseconds.
JD B C St at ist ics
The following table contains a list of the supported datasource JD BC statistics:
T ab le 6 .16 . JD B C St at ist ics
N ame
D escrip t io n
P repared Statement
C acheAccessC o unt
P repared Statement
C acheAd d C o unt
P repared Statement
C acheC urrentSi ze
P repared Statement
C acheD el eteC o unt
P repared Statement
C acheHi tC o unt
P repared Statement
C acheMi ssC o unt
The number of times that the statement cache was accessed.

The number of statements added to the statement cache.
The number of prepared and callable statements currently cached in the
statement cache.
The number of statements discarded from the cache.
The number of times that statements from the cache were used.
The number of times that a statement request could not be satisfied with a
statement from the cache.
You can enable C o re and JD BC statistics using appropriately modified versions of the following
commands:
/subsystem=datasources/data-source=ExampleDS/statistics=pool:writeattribute(name=statistics-enabled,value=true)
/subsystem=datasources/data-source=ExampleDS/statistics=jdbc:writeattribute(name=statistics-enabled,value=true)
Report a bug
6.8. Example Dat asources

6.8.1. Example Post greSQL Dat asource
The example below is a PostgreSQL datasource configuration. The datasource has been enabled, a
user has been added, and validation options have been set.
Examp le 6 .17. Po st SQ L d at aso u rce co n f ig u rat io n

<datasources>
<datasource jndi-name="java:jboss/PostgresDS" pool-name="PostgresDS">
<connectionurl>jdbc:postgresql://localhost:5432/postgresdb</connection-url>
<driver>postgresql</driver>
<security>
166
<password>admin</password>
</security>
<validation>
<validate-on-match>true</validate-on-match>
<background-validation>false</background-validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidCo
nnectionChecker"></valid-connection-checker>
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExcepti
onSorter"></exception-sorter>
</validation>
</datasource>
<drivers>
<driver name="postgresql" module="org.postgresql">
<xa-datasource-class>org.postgresql.xa.PGXADataSource</xadatasource-class>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the PostgreSQL datasource above.
Examp le 6 .18. mo d u le.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>
Report a bug
6.8.2. Example Post greSQL XA Dat asource

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.
Examp le 6 .19 . Po st SQ L XA d at aso u rce

<datasources>
<xa-datasource jndi-name="java:jboss/PostgresXADS" poolname="PostgresXADS">
<driver>postgresql</driver>
<xa-datasource-property name="ServerName">localhost</xadatasource-property>
<xa-datasource-property name="PortNumber">5432</xa-datasource-
167
property>
<xa-datasource-property name="DatabaseName">postgresdb</xadatasource-property>
<security>
</security>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidCo
nnectionChecker">
</valid-connection-checker>
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExcepti
onSorter">
</exception-sorter>
</validation>
</xa-datasource>
<drivers>
<driver name="postgresql" module="org.postgresql">
<xa-datasource-class>org.postgresql.xa.PGXADataSource</xadatasource-class>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the PostgreSQL XA datasource above.

<module xmlns="urn:jboss:module:1.1" name="org.postgresql">
<resources>
<resource-root path="postgresql-9.1-902.jdbc4.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.3. Example MySQL Dat asource

The example below is a MySQL datasource configuration. The datasource has been enabled, a user
has been added, and validation options have been set.
Examp le 6 .21. MySQ L d at aso u rce co n f ig u rat io n
168
<datasources>
<datasource jndi-name="java:jboss/MySqlDS" pool-name="MySqlDS">
<connection-url>jdbc:mysql://mysqllocalhost:3306/jbossdb</connection-url>
<driver>mysql</driver>
<security>
</security>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnection
Checker"></valid-connection-checker>
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
"></exception-sorter>
</validation>
</datasource>
<drivers>
<driver name="mysql" module="com.mysql">
<xa-datasourceclass>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasourceclass>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the MySQL datasource above.

<module xmlns="urn:jboss:module:1.1" name="com.mysql">
<resources>
<resource-root path="mysql-connector-java-5.0.8-bin.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.4 . Example MySQL XA Dat asource

The example below is a MySQL XA datasource configuration. The datasource has been enabled, a
Examp le 6 .23. MySQ L XA d at aso u rce
169
<datasources>
<xa-datasource jndi-name="java:jboss/MysqlXADS" poolname="MysqlXADS">
<driver>mysql</driver>
<xa-datasource-property name="DatabaseName">mysqldb</xa-datasourceproperty>
<security>
</security>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnection
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
</validation>
</xa-datasource>
<drivers>
<driver name="mysql" module="com.mysql">
<xa-datasourceclass>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasourceclass>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the MySQL XA datasource above.
Examp le 6 .24 . mo d u le.xml

<resources>
<resource-root path="mysql-connector-java-5.0.8-bin.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.5. Example Oracle Dat asource
170
Note
The example below is an Oracle datasource configuration. The datasource has been enabled, a user
Examp le 6 .25. O racle d at aso u rce co n f ig u rat io n

<datasources>
<datasource jndi-name="java:/OracleDS" pool-name="OracleDS">
<connection-url>jdbc:oracle:thin:@ localhost:1521:XE</connectionurl>
<driver>oracle</driver>
<security>
</security>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnecti
onChecker"></valid-connection-checker>
<stale-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnecti
onChecker"></stale-connection-checker>
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSort
er"></exception-sorter>
</validation>
</datasource>
<drivers>
<driver name="oracle" module="com.oracle">
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the Oracle datasource above.

<module xmlns="urn:jboss:module:1.1" name="com.oracle">
<resources>
<resource-root path="ojdbc6.jar"/>
</resources>
<dependencies>
171
</dependencies>
</module>
Report a bug
6.8.6. Example Oracle XA Dat asource
Note
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
GRANT
GRANT
GRANT
11g)
SELECT ON sys.dba_pending_transactions TO user;

SELECT ON sys.pending_trans$ TO user;
SELECT ON sys.dba_2pc_pending TO user;
EXECUTE ON sys.dbms_xa TO user; (If using Oracle 10g R2 (patched) or Oracle
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
Examp le 6 .27. O racle XA d at aso u rce

<datasources>
<xa-datasource jndi-name="java:/XAOracleDS" pool-name="XAOracleDS">
<driver>oracle</driver>
<xa-datasource-property name="URL">jdbc:oracle:oci8:@ tc</xadatasource-property>
<security>
</security>
<xa-pool>
<is-same-rm-override>false</is-same-rm-override>
<no-tx-separate-pools />
172
</xa-pool>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnecti
<stale-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnecti
onChecker"></stale-connection-checker>
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSort
</validation>
</xa-datasource>
<drivers>
<driver name="oracle" module="com.oracle">
<xa-datasourceclass>oracle.jdbc.xa.client.OracleXADataSource</xa-datasource-class>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the Oracle XA datasource above.

<module xmlns="urn:jboss:module:1.1" name="com.oracle">
<resources>
<resource-root path="ojdbc6.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.7. Example Microsoft SQLServer Dat asource

The example below is a Microsoft SQLServer datasource configuration. The datasource has been
Examp le 6 .29 . SQ Lserver d at aso u rce co n f ig u rat io n

<datasources>
<datasource jndi-name="java:/MSSQLDS" pool-name="MSSQLDS">
<connectionurl>jdbc:sqlserver://localhost:1433;DatabaseName=MyDatabase</connection
-url>
173
<driver>sqlserver</driver>
<security>
</security>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnection
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
</validation>
</datasource>
<drivers>
<driver name="sqlserver" module="com.microsoft">
</datasources>
The example below is a mo d ul e. xml file for the Microsoft SQLServer datasource above.

<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
<resources>
<resource-root path="sqljdbc4.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.8. Example Microsoft SQLServer XA Dat asource

The example below is a Microsoft SQLServer XA datasource configuration. The datasource has been
Examp le 6 .31. SQ Lserver XA d at aso u rce

<datasources>
<xa-datasource jndi-name="java:/MSSQLXADS" pool-name="MSSQLXADS">
<driver>sqlserver</driver>
<xa-datasource-property name="DatabaseName">mssqldb</xa-datasourceproperty>
<xa-datasource-property name="SelectMethod">cursor</xa-datasource-
174
property>
<security>
</security>
<xa-pool>
</xa-pool>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnection
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLExceptionSorter
</validation>
</xa-datasource>
<drivers>
<driver name="sqlserver" module="com.microsoft">
<xa-datasourceclass>com.microsoft.sqlserver.jdbc.SQLServerXADataSource</xadatasource-class>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the Microsoft SQLServer XA datasource above.

<module xmlns="urn:jboss:module:1.1" name="com.microsoft">
<resources>
<resource-root path="sqljdbc4.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.9. Example IBM DB2 Dat asource

The example below is an IBM D B2 datasource configuration. The datasource has been enabled, a
Examp le 6 .33. IB M D B 2 d at aso u rce co n f ig u rat io n
175
<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>
</security>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChec
ker"></valid-connection-checker>
<stale-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChec
ker"></stale-connection-checker>
<exception-sorter classname="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 mo d ul e. xml file for the IBM D B2 datasource above.

<module xmlns="urn:jboss:module:1.1" name="com.ibm">
<resources>
<resource-root path="db2jcc4.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.10. Example IBM DB2 XA Dat asource

The example below is an IBM D B2 XA datasource configuration. The datasource has been enabled,
a user has been added and validation options have been set.
176
Examp le 6 .35. IB M D B 2 XA d at aso u rce co n f ig u rat io n

<datasources>
<xa-datasource jndi-name="java:/DB2XADS" pool-name="DB2XADS">
<driver>ibmdb2</driver>
<xa-datasource-property name="DatabaseName">ibmdb2db</xadatasource-property>
<xa-datasource-property name="ServerName">hostname</xa-datasourceproperty>
<xa-datasource-property name="PortNumber">port</xa-datasourceproperty>
<security>
</security>
<xa-pool>
</xa-pool>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChec
ker"></valid-connection-checker>
<stale-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChec
ker"></stale-connection-checker>
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter">
</exception-sorter>
</validation>
<recovery>
<recover-plugin classname="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</xadatasource-class>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the IBM D B2 XA datasource above.

<module xmlns="urn:jboss:module:1.1" name="com.ibm">
177
<resources>
<resource-root path="db2jcc4.jar"/>
<resource-root path="db2jcc_license_cisuz.jar"/>
<resource-root path="db2jcc_license_cu.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.11. Example Sybase Dat asource

The example below is a Sybase datasource configuration. The datasource has been enabled, a user
Examp le 6 .37. Syb ase d at aso u rce co n f ig u rat io n

<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>
</security>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnecti
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSort
</validation>
</datasource>
<drivers>
<driver name="sybase" module="com.sybase">
<datasourceclass>com.sybase.jdbc4.jdbc.SybDataSource</datasource-class>
<xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xadatasource-class>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the Sybase datasource above.
178

<module xmlns="urn:jboss:module:1.1" name="com.sybase">
<resources>
<resource-root path="jconn2.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
6.8.12. Example Sybase XA Dat asource

The example below is a Sybase XA datasource configuration. The datasource has been enabled, a
Examp le 6 .39 . Syb ase XA d at aso u rce co n f ig u rat io n

<datasources>
<xa-datasource jndi-name="java:jboss/SybaseXADS" poolname="SybaseXADS" enabled="true">
<xa-datasource-property name="NetworkProtocol">Tds</xa-datasourceproperty>
<xa-datasource-property name="ServerName">myserver</xa-datasourceproperty>
<xa-datasource-property name="PortNumber">4100</xa-datasourceproperty>
<xa-datasource-property name="DatabaseName">mydatabase</xadatasource-property>
<security>
</security>
<xa-pool>
</xa-pool>
<validation>
<valid-connection-checker classname="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnecti
<exception-sorter classname="org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSort
</validation>
</xa-datasource>
<drivers>
<driver name="sybase" module="com.sybase">
<datasource-
179
class>com.sybase.jdbc4.jdbc.SybDataSource</datasource-class>
<xa-datasource-class>com.sybase.jdbc4.jdbc.SybXADataSource</xadatasource-class>
</driver>
</drivers>
</datasources>
The example below is a mo d ul e. xml file for the Sybase XA datasource above.
Examp le 6 .4 0. mo d u le.xml
<module xmlns="urn:jboss:module:1.1" name="com.sybase">
<resources>
<resource-root path="jconn2.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
Report a bug
180
Chapter 7. Configuring Modules

7.1. Int roduct ion
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.
St at ic Mo d u les
Static Modules are predefined in the EAP_HOME/mo d ul es/ directory of the application
server. Each sub-directory represents one module and defines a mai n/ subdirectory that
contains a configuration file (mo d ul e. xml ) and any required JAR files. The name of the
module is defined in the mo d ul e. 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.
Examp le 7.1. Examp le mo d u le.xml f ile

<?xml version="1.0" encoding="UTF-8"?>
<resources>
<resource-root path="mysql-connector-java-5.1.15.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
The module name, co m. mysq l , should match the directory structure for the module,
excluding the mai n/ subdirectory name.
The modules provided in JBoss EAP distributions are located in a system directory within
the EAP_HOME/mo d ul es 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/mo d ul es
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 JBO SS_MO D ULEP AT H environment variable to change the locations in which
181
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 JBO SS_MO D ULEP AT H.
D yn amic Mo d u les
D ynamic 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.
Report a bug
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.
Report a bug
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.
D eployed 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.
Exp licit D ep en d en cies
Explicit dependencies are declared by the developer in the configuration file. Static modules can
declare dependencies in the mo d ul e. xml file. D ynamic modules can have dependencies declared
in the MANIFEST . MF or jbo ss-d epl o yment-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. D ependencies must be available when the module is loaded.
Imp licit D ep en d en cies
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.
D eployments can also be configured to exclude specific implicit dependencies. This is done with the
jbo ss-d epl o yment-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.
182
Chapt er 7 . Configuring Modules
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.
Examp le 7.2. Mo d u le d ep en d en cies

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 jbo ssd epl o yment-structure. xml deployment descriptor.
Report a bug
7.1.4 . Subdeployment Class Loader Isolat ion

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.
Report a bug
7.2. Disable Subdeployment Module Isolat ion for All Deployment s

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. St o p t h e server
Halt the JBoss EAP 6 server.
2. O p en t h e server co n f ig u rat io n f ile
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
d o mai n/co nfi g urati o n/d o mai n. xml and
183
stand al o ne/co nfi g urati o n/stand al o ne. xml for managed domains and standalone
servers respectively.
3. Lo cat e t h e EE Su b syst em C o n f ig u rat io n
Locate the EE Subsystem configuration element in the configuration file. The <pro fi l e>
element of the configuration file contains several subsystem elements. The EE Subsystem
element has the namespace of urn: jbo ss: d o mai n: 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. R ep lace self - clo sin g t ag s if n ecessary
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. Ad d ear- su b d ep lo ymen t s- iso lat ed elemen t
Add the ear-subd epl o yments-i so l ated element as a child of the EE Subsystem element
and add the content of fal se like this:
<subsystem xmlns="urn:jboss:domain:ee:1.2" ><ear-subdeploymentsisolated>false</ear-subdeployments-isolated></subsystem>
6. St art t h e server
Relaunch the JBoss EAP 6 server to start it running with the new configuration.
R esu lt :
The server will now be running with Subdeployment Module Isolation disabled for all deployments.
Report a bug
7.3. Add a Module t o All Deployment s

This task shows how JBoss administrators can define a list of global modules.
Prereq u isit es
1. You must know the name of the modules that are to be configured as global modules. Refer to
184
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, D ynamic Module Naming to
determine the module name.
Pro ced u re 7.1. Ad d a mo d u le t o t h e list o f g lo b al mo d u les
1. Login to the management console. Section 3.3.2, Log in to the Management Console
2. Navigate to the EE Subsystem panel.
a. Select the C o nfi g urati o n tab from the top of the console.
b. D o main Mo d e O n ly
i. Select the appropriate profile from the drop-down box in the top left.
c. Expand the Su b syst ems menu on the left of the console.
d. Select C o n t ain er EE from the menu on the left of the console.
3. Click Ad d in the Subsystem D efaul ts section. The C reate Mo d ul e dialog appears.
4. Type in the name of the module and optionally the module slot.
5. Click Save to add the new global module, or click C ancel 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 C ancel , the dialog will close and no changes will be made.
R esu lt
The modules added to the list of global modules will be added as dependencies to every deployment.
Report a bug
7.4 . Creat e a Cust om 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.
Pro ced u re 7.2. C reat e a C u st o m Mo d u le
1. Create and populate the mo d ul e/ directory structure.
a. Create a directory structure under the EAP_HOME/mo d ul e directory to contain the
files and JARs. For example:
$ cd EAP_HOME/mo d ul es/
$ mkd i r -p myo rg -co nf/mai n/pro perti es
b. Move the properties files to the EAP_HOME/mo d ul es/myo rg co nf/mai n/pro perti es/ directory you created in the previous step.
c. Create a mo d ul e. xml file in the EAP_HOME/mo d ul es/myo rg -co nf/mai n/
directory containing the following XML:
185
<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.
A. Follow these steps to modify the server configuration file using the Management CLI.
a. Start the server and connect to the Management CLI.
A. For Linux, enter the following at the command line:
EAP_HOME/bin/jboss-cli.sh --connect
B. 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
b. To create the myo rg -co nf <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:
B. Follow these steps if you prefer to manually edit the server configuration file.
a. 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/stand al o ne/co nfi g urati o n/stand al o ne. xml file, or the
EAP_HOME/d o mai n/co nfi g urati o n/d o mai n. xml file if you are running a
managed domain.
b. Find the ee subsystem and add the global module for myo rg -co nf. The following
is an example of the ee subsystem element, modified to include the myo rg -co nf
element:
Examp le 7.3. myo rg -co nf elemen t

<subsystem xmlns="urn:jboss:domain:ee:1.0" >
<global-modules>
<module name="myorg-conf" slot="main" />
</global-modules>
</subsystem>
186
3. Assuming you copied a file named my. pro perti es into the correct module location, you are
now able to load properties files using code similar to the following:
Examp le 7.4 . Lo ad p ro p ert ies f ile

Thread.currentThread().getContextClassLoader().getResource("my.pr
operties");
Report a bug
7.5. Define an Ext ernal JBoss Module Direct ory

Su mmary
By default, JBoss EAP looks for modules in the EAP_HOME/mo d ul es/ directory. You can direct
JBoss EAP to look in one or more external directories by defining a JBO SS_MO D ULEP AT H
environment variable or by setting the variable in the startup configuration file. This topic describes
both methods.
Pro ced u re 7.3. Set t h e JB O SS_MO D U LEPAT H En viro n men t Variab le
To specify one or more external module directories, define the JBO SS_MO D ULEP AT H environment
variable.
For Linux, use a colon to delimit a list of directories. For example:
Examp le 7.5. JBO SS_MO D ULEP AT H en viro n men t variab le

export
JBOSS_MODULEPATH=EAP_HOME/modules/:/home/username/external/modules/d
irectory/
For Windows, use a semicolon to delimit a list of directories. For example:
Examp le 7.6 . JBO SS_MO D ULEP AT H en viro n men t variab le

SET JBOSS_MODULEPATH=EAP_HOME\modules\;D:\JBoss-Modules\
Pro ced u re 7.4 . Set t h e JB O SS_MO D U LEPAT H Variab le in t h e St art u p C o n f ig u rat io n File
If you prefer not to set a global environment variable, you can set the JBO SS_MO D ULEP AT H
variable in the JBoss EAP startup configuration file. If you are running a standalone server, this is
the EAP_HOME/bi n/stand al o ne. co nf file. If the server is running in a managed domain, this
is the EAP_HOME/bi n/d o mai n. co nf file.
The following is an example of the command that sets the JBO SS_MO D ULEP AT H variable in the
stand al o ne. co nf file:
187
Examp le 7.7. stand al o ne. co nf en t ry

JBOSS_MODULEPATH="EAP_HOME/modules/:/home/username/external/modules/
directory/"
Report a bug
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.
Report a bug
7.6.2. Dynamic Module Naming

All deployments are loaded as modules by JBoss EAP 6 and named according to the following
conventions.
D eployments of WAR and JAR files are named with the following format:
deployment.DEPLOYMENT_NAME
For example, i nvento ry. war and sto re. jar will have the module names of
d epl o yment. i nvento ry. war and d epl o yment. sto re. jar respectively.
Subdeployments within an Enterprise Archive are named with the following format:
deployment.EAR_NAME.SUBDEPLOYMENT_NAME
For example, the subdeployment of repo rts. war within the enterprise archive acco unts. ear
will have the module name of d epl o yment. acco unts. ear. repo rts. war.
Report a bug
188
Chapter 8. Jsvc
8.1. Int roduct ion
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 Nati ve Uti l i ti es fo r Wi nd o ws
Server download available from the Red Hat Customer Portal.
Report a bug
8.1.2. St art and St op 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.
Prereq u isit es
If JBoss EAP was installed using the Z ip 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.
St an d alo n e Mo d e
The following instructions are to start or stop JBoss EAP in standalone mode.
189
T ab le 8.1. Jsvc File lo cat io n s Fo r Z ip in st allat io n s - St an d alo n e Mo d e

File R ef eren ce in
In st ru ct io n s
File Lo cat io n
EAP-HOME
JSVC-BIN
JSVC-JAR
${eap-installation-location}/jboss-eap-${version}
EAP_HOME/modules/system/layers/base/native/sbin/jsvc
EAP_HOME/modules/system/layers/base/native/sbin/commonsdaemon.jar
EAP_HOME/standalone/configuration
EAP_HOME/standalone/log
CONF-D IR
LOG-D IR
T ab le 8.2. Jsvc File Lo cat io n s f o r R PM In st allat io n s - St an d alo n e Mo d e

In st ru ct io n s
File Lo cat io n
EAP-HOME
JSVC-BIN
JSVC-JAR
/usr/share/jbossas
/usr/bin/jsvc-eap6/jsvc
/etc/jbossas/standalone
/var/log/jbossas/standalone
CONF-D IR
LOG-D IR
St art JB o ss EAP in St an d alo n e Mo d e

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
St o p JB o ss EAP in St an d alo n e Mo d e
JSVC_BIN \
-stop \
-user jboss \
190
\
\
Chapt er 8 . Jsvc
-D[Standalone] -XX:+UseCompressedOops -Xms1303m \

-Djava.net.preferIPv4Stack=true \
-Dorg.jboss.boot.log.file=LOG_DIR/server.log \
-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
D o main Mo d e
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.
T ab le 8.3. Jsvc File Lo cat io n s f o r Z ip In st allat io n s - D o main Mo d e
In st ru ct io n s
File Lo cat io n
EAP-HOME
JSVC-BIN
JSVC-JAR
${eap-installation-location}/jboss-eap-${version}
EAP_HOME/modules/system/layers/base/native/sbin/jsvc
EAP_HOME/domain/configuration
EAP_HOME/domain/log
CONF-D IR
LOG-D IR
T ab le 8.4 . Jsvc File Lo cat io n s f o r R PM In st allat io n s - D o main Mo d e

In st ru ct io n s
File Lo cat io n
EAP-HOME
JSVC-BIN
JSVC-JAR
/usr/share/jbossas
/usr/bin/jsvc-eap6/jsvc
/etc/jbossas/domain
/var/log/jbossas/domain
CONF-D IR
LOG-D IR
St art JB o ss EAP in D o main Mo d e

JSVC_BIN \
\
\
-user jboss \
-nodetach -D"[Process Controller]" -server -Xms64m \
191
-Dorg.jboss.boot.log.file=LOG_DIR/process-controller.log \
-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 \
-server -Xms64m -Xmx512m -XX:MaxPermSize=256m \
-Djava.awt.headless=true -- -default-jvm $JAVA_HOME/bin/java
St o p JB o ss EAP in D o main Mo d e
JSVC_BIN \
-stop \
\
\
-user jboss \
-nodetach -D"[Process Controller]" -server -Xms64m \
-Dorg.jboss.boot.log.file=LOG_DIR/process-controller.log \
-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 \
-server -Xms64m -Xmx512m -XX:MaxPermSize=256m \
-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.
192
Chapt er 8 . Jsvc
Report a bug
193
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.
Report a bug
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 .
Report a bug
9.3. About Aut hent icat or Valves

An authenticator valve is a valve that authenticates the credentials of a request. Such valve is a subclass of o rg . apache. catal i na. authenti cato r. Authenti cato rBase and overrides the
authenti cate(R eq uest req uest, R espo nse respo nse, Lo g i nC o nfi g co nfi g ) method.
This can be used to implement additional authentication schemes.
Report a bug
9.4 . Inst all 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- req u isit ies:
The valve must already be created and packaged in a JAR file.
194
Chapt er 9 . G lobal Valves
A mo d ul e. xml file must already be created for the module.

Refer to Section 7.1.1, Modules for an example of mo d ul e. xml file.
Pro ced u re 9 .1. In st all a G lo b al Mo d u le
1. C reat e mo d u le in st allat io n d irect o ry
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. C o p y f iles
Copy the JAR and mo d ul e. 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.
Report a bug
9.5. Configure a Global Valve

Global valves are enabled and configured in the web subsystem. This is done using the JBoss CLI
tool.
Pro ced u re 9 .2. C o n f ig u re a G lo b al Valve
1. En ab le t h e Valve
Use the ad d operation to add a new valve entry.
/subsystem=web/valve=VALVENAME:add(module="MODULENAME",classname="CLASSNAME")
You need to specify the following values:
VALVENAME, the name that is used to refer to this valve in application configuration.
MO D ULENAME, the module that contains the value being configured.
C LASSNAME, 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. O p t io n ally: Sp ecif y Paramet ers
195
If the valve has configuration parameters, specify these with the ad d -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.
P AR AMNAME, the name of the parameter that is being configured for specific valve.
P AR AMVALUE, the value of the specified parameter.
For example:
Examp le 9 .1. Valve co n f ig u rat io n

/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.
Report a bug
196
Chapt er 9 . G lobal Valves
Chapter 10. Application Deployment

10.1. About Applicat ion 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 ID E such
as JBoss D eveloper Studio, or deployment and undeployment via Maven.
Ad min ist rat io n
Section 10.2.2, Enable a D eployed Application Using the Management Console
Section 10.2.3, D isable a D eployed Application Using the Management Console
Man ag emen t C LI
Section 10.3.4, D eploy an Application in a Managed D omain Using the Management CLI
Section 10.3.2, D eploy an Application in a Standalone Server Using the Management CLI
Section 10.3.5, Undeploy an Application in a Managed D omain Using the Management CLI
Section 10.3.3, Undeploy an Application in a Standalone Server Using the Management CLI
Section 10.3.1, Manage Application D eployment in the Management CLI
D evelo p men t
D ep lo ymen t Scan n er
Section 10.5.7, Configure the D eployment Scanner
Section 10.5.2, D eploy an Application to a Standalone Server Instance with the D eployment
Scanner
Section 10.5.3, Undeploy an Application from a Standalone Server Instance with the
D eployment Scanner
Section 10.5.4, Redeploy an Application to a Standalone Server Instance with the
D eployment Scanner
Section 10.5.8, Configure the D eployment Scanner with the Management CLI
Section 10.5.6, Reference for D eployment Scanner Attributes
Section 10.5.5, Reference for D eployment Scanner Marker Files
Maven
Section 10.6.2, D eploy an Application with Maven
Section 10.6.3, Undeploy an Application with Maven
197
Note
Before deploying any application, you can enable validation for deployment descriptors. This
can be done by setting the o rg . jbo ss. metad ata. parser. val i d ate 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
Report a bug
10.2. Deploy wit h t he Management Console

10.2.1. Manage Applicat ion Deployment in t he Management Console
D eploying 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.
Report a bug
10.2.2. Enable a Deployed Applicat ion Using t he Management Console

Prereq u isit es
Section 3.3.8, Add a D eployment in the Management Console
Pro ced u re 10.1. En ab le a D ep lo yed Ap p licat io n u sin g t h e Man ag emen t C o n so le
Select the D epl o yments 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.
A. En ab le an ap p licat io n o n a st an d alo n e server in st an ce
198
Chapt er 1 0 . Applicat ion Deployment
The Avai l abl e D epl o yments table shows all available application deployments and their
status.
a. To enable an application in a standalone server instance, select the application, then
click En/D i sabl e.
Fig u re 10.1. Availab le d ep lo ymen t s

b. Click C o nfi rm to confirm that the application will be enabled on the server instance.
Fig u re 10.2. Availab le d ep lo ymen t s in a st an d alo n e server

B. En ab le an ap p licat io n in a man ag ed d o main
199
The C o ntent R epo si to ry tab contains an Avai l abl e D epl o yment C o ntent table
showing all available application deployments and their status.
a. To enable an application in a Managed D omain, select the application to be deployed.
Click Assi g n above the Avai l abl e D epl o yment C o ntent table.
Fig u re 10.3. Availab le d ep lo ymen t s in a man ag ed d o main

b. Check the boxes for each of the server groups that you want the application to be
added to and click Save to finish.
c. Select Server G ro ups tab to view the Server G ro ups table.
Fig u re 10.4 . C o n f irmat io n o f ap p licat io n d ep lo ymen t t o server g ro u p s
200
d. If your application is not already enabled, you can enable it now by clicking on Vi ew
and then clicking on the En/D i sabl e button. Click C o nfi rm to confirm that the
application will be enabled on the server instance.
R esu lt
The application is enabled on the relevant server or server group.
Report a bug
10.2.3. Disable a Deployed Applicat ion Using t he Management Console

Prereq u isit es
Pro ced u re 10.2. D isab le a D ep lo yed Ap p licat io n u sin g t h e Man ag emen t C o n so le
Select the D epl o yment 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.
A. D isab le a d ep lo yed ap p licat io n o n a St an d alo n e server in st an ce
status.
201
a. Select the application to be disabled. Click En/D i sabl e to disable the selected
application.
b. Click C o nfi rm to confirm that the application will be disabled on the server instance.
B. D isab le a d ep lo yed ap p licat io n o n a man ag ed d o main
The D epl o yments screen contains a C o ntent R epo si to ry tab. The Avai l abl e
D epl o yment C o ntent table shows all available application deployments and their status.
a. Select the Server G ro ups tab to view the server groups.
Fig u re 10.6 . Server g ro u p d ep lo ymen t s

b. Select the name of the server group in the Server G ro up table to undeploy an
application from. Click Vi ew to see the applications.
c. Select the application and click En/D i sabl e to disable the application for the
selected server.
d. Click C o nfi rm to confirm that the application will be disabled on the server instance.
e. Repeat as required for other server groups. The application status is confirmed for
each server group in the G ro up D epl o yments table for that server group.
R esu lt
The application is disabled from the relevant server or server group.
Report a bug
10.2.4 . Undeploy an Applicat ion Using t he Management Console

Prereq u isit es
202

Section 10.2.3, D isable a D eployed Application Using the Management Console
Pro ced u re 10.3. U n d ep lo y an Ap p licat io n U sin g t h e Man ag emen t C o n so le
Select the D epl o yments 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.
A. U n d ep lo y a d ep lo yed ap p licat io n f ro m a St an d alo n e server in st an ce
status.

a. Select the application to be undeployed. Click R emo ve to undeploy the selected
application.
b. Click C o nfi rm to confirm that the application will be undeployed on the server
instance.
B. U n d ep lo y a d ep lo yed ap p licat io n f ro m a man ag ed d o main
The D epl o yments screen contains a C o ntent R epo si to ry tab. The Avai l abl e
D epl o yment C o ntent table shows all available application deployments and their status.
203
a. Select the Server G ro ups tab to view the server groups and the status of their
deployed applications.
Fig u re 10.8. Server g ro u p d ep lo ymen t s

b. Select the name of the server group in the Server G ro up table to undeploy an
application from. Click Vi ew to see the applications.
c. Select the application and click R emo ve to undeploy the application for the selected
server.
d. Click C o nfi rm to confirm that the application will be undeployed on the server
instance.
e. Repeat as required for other server groups. The application status is confirmed for
each server group in the G ro up D epl o yments table for that server group.
R esu lt
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.
Report a bug
10.3. Deploy wit h t he Management CLI

10.3.1. Manage Applicat ion Deployment in t he Management CLI
D eploying 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.
204
Report a bug
10.3.2. Deploy an Applicat ion in a St andalone Server Using t he Management

CLI
Prereq u isit es
Pro ced u re 10.4 . D ep lo y an Ap p licat io n in a St an d alo n e Server
R u n t h e d epl o y co mman d
From the Management CLI, enter the d epl o y command with the path to the application
deployment.
Examp le 10.1. T h e D ep lo y co mman d

[standalone@ localhost:9999 /] d epl o y /path/to/test-application.war
Note that a successful deploy does not produce any output to the CLI.
R esu lt
The specified application is now deployed in the standalone server.
Report a bug
10.3.3. Undeploy an Applicat ion in a St andalone Server Using t he Management

CLI
Prereq u isit es
Section 10.3.2, D eploy an Application in a Standalone Server Using the Management CLI
Pro ced u re 10.5. U n d ep lo y an Ap p licat io n in a St an d alo n e Server
By default the und epl o y command will undeploy and delete the deployment content from a
standalone instance of JBoss EAP. To retain the deployment content, add the parameter --keepcontent.
R u n t h e und epl o y co mman d
To undeploy the application and delete the deployment content, enter the Management CLI
und epl o y command with the filename of the application deployment.
[standalone@ localhost:9999 /] und epl o y test-application.war
205
To undeploy the application, but retain the deployment content, enter the Management CLI
und epl o y command with the filename of the application deployment and the parameter --keepcontent.
[standalone@ localhost:9999 /] und epl o y test-application.war --keepcontent
R esu lt
The specified application is now undeployed. Note that the und epl o y command does not produce
any output to the Management CLI if it is successful.
Report a bug
10.3.4 . Deploy an Applicat ion in a Managed Domain Using t he Management CLI

Prereq u isit es
Pro ced u re 10.6 . D ep lo y an Ap p licat io n in a Man ag ed D o main
R u n t h e d epl o y co mman d
From the Management CLI, enter the d epl o y command with the path to the application
deployment. Include the --all-server-groups parameter to deploy to all server groups.
[domain@ localhost:9999 /] d epl o y /path/to/test-application.war --al l server-g ro ups
A. Alternatively, define specific server groups for the deployment with the --server-groups
parameter.
[domain@ localhost:9999 /] d epl o y /path/to/test-application.war -server-g ro ups= server_group_1,server_group_2
Note that a successful deploy does not produce any output to the CLI.
R esu lt
The specified application is now deployed to a server group in your managed domain.
Report a bug
10.3.5. Undeploy an Applicat ion in a Managed Domain Using t he Management

CLI
Prereq u isit es
206
Section 10.3.4, D eploy an Application in a Managed D omain Using the Management CLI
Pro ced u re 10.7. U n d ep lo y an Ap p licat io n in a Man ag ed D o main
R u n t h e und epl o y co mman d
From the Management CLI, enter the und epl o y 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.
[d o mai n@ l o cal ho st: 9 9 9 9 /] und epl o y test-application.war --allrelevant-server-groups
Note that a successful undeploy does not produce any output to the CLI.
R esu lt
The specified application is now undeployed.
Report a bug
10.4 . Deploy wit h t he HT T P API

10.4 .1. Deploy an applicat ion using t he HT T P API
Su mmary
Applications can be deployed via the HTTP API using the following instructions.
Prereq u isit es
Add the user for the management interfaces. For information on creating the initial administrative
user for the remote management interfaces, refer Section 4.2.1, Add the User for the Management
Interfaces
Pro ced u re 10.8. D ep lo y an ap p licat io n u sin g H T T P API
Use either the d epl o y or und epl o y command relevant to your requirements.
Examp le 10.2. D ep lo y an d u n d ep lo y co mman d

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
207

"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
"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
"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.
Report a bug
10.5. Deploy wit h t he Deployment Scanner

10.5.1. Manage Applicat ion Deployment in t he Deployment Scanner
D eploying 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.
Report a bug
10.5.2. Deploy an Applicat ion t o a St andalone Server Inst ance wit h t he

Deployment Scanner
Prereq u isit es
Su mmary
208
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 D eployment 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.
Pro ced u re 10.9 . U se t h e D ep lo ymen t Scan n er t o D ep lo y Ap p licat io n s
1. C o p y co n t en t t o t h e d ep lo ymen t f o ld er
Copy the application file to the deployment folder found at
EAP_HOME/stand al o ne/d epl o yments/.
2. D ep lo ymen t scan n in g mo d es
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 D eployment Scanner with the Management CLI .
A. Au t o mat ic d ep lo ymen t
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 D eployment Scanner with the
Management CLI .
B. Man u al d ep lo ymen t
The deployment scanner requires a marker file to trigger the deployment process. The
following example uses the Unix to uch command to create a new . d o d epl o y file.
Examp le 10.3. D ep lo y wit h t h e to uch co mman d

[user@ host bin]$ to uch
$EAP_HOME/standalone/deployments/example.war.dodeploy
R esu lt
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 Enabl ed in the
Management Console.
Examp le 10.4 . D ep lo ymen t f o ld er co n t en t s af t er d ep lo ymen t

example.war
example.war.deployed
Report a bug
10.5.3. Undeploy an Applicat ion from a St andalone Server Inst ance wit h t he
Deployment Scanner
209
Prereq u isit es
Scanner
Su mmary
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
D eployment 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.
Pro ced u re 10.10. U n d ep lo y an Ap p licat io n u sin g o n e o f t h ese Met h o d s

U n d ep lo y t h e ap p licat io n
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.
A. U n d ep lo y b y d elet in g t h e marker f ile
D elete the deployed application's exampl e. war. d epl o yed marker file to trigger the
deployment scanner to begin undeploying the application from the runtime.
R esu lt
The deployment scanner undeploys the application and creates a
exampl e. war. und epl o yed marker file. The application remains in the deployment
folder.
B. U n d ep lo y b y remo vin g t h e ap p licat io n
210
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.
R esu lt
The deployment scanner undeploys the application and creates a
fi l ename. fi l etype. und epl o yed marker file. The application is not present in
the deployment folder.
R esu lt
The application file is undeployed from the application server and is not visible in the D epl o yments
screen of the Management Console.
Report a bug
10.5.4 . Redeploy an Applicat ion t o a St andalone Server Inst ance wit h t he

Deployment Scanner
Prereq u isit es
Scanner
Su mmary
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
D eployment 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.
Pro ced u re 10.11. R ed ep lo y an Ap p licat io n t o a St an d alo n e Server
211
R ed ep lo y t h e ap p licat io n
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.
A. R ed ep lo y b y alt erin g t h e marker f ile
Trigger the deployment scanner redeployment by altering the marker file's access and
modification timestamp. In the following Linux example, a Unix to uch command is used.
Examp le 10.5. R ed ep lo y wit h t h e U n ix to uch co mman d

[user@ host bin]$ to uch
EAP_HOME/standalone/deployments/example.war.dodeploy
R esu lt
The deployment scanner detects a change in the marker file and redeploys the application. A
new . d epl o yed file marker replaces the previous.
B. R ed ep lo y b y creat in g a n ew . d o d epl o y marker f ile
Trigger the deployment scanner redeployment by creating a new . d o d epl o y marker file.
Refer to the manual deployment instructions in Section 10.5.2, D eploy an Application to a
Standalone Server Instance with the D eployment Scanner .
C. R ed ep lo y b y d elet in g t h e marker f ile
As described in Section 10.5.5, Reference for D eployment Scanner Marker Files , deleting a
deployed application's . d epl o yed marker file will trigger an undeployment and create an
. und epl o yed marker. D eleting the undeployment marker will trigger the deployment cycle
again. Refer to Section 10.5.3, Undeploy an Application from a Standalone Server Instance
with the D eployment Scanner for further information.
R esu lt
The application file is redeployed.
Report a bug
10.5.5. Reference for Deployment Scanner Marker Files

Marker f iles
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.
Examp le 10.6 . Marker f ile examp le
212
The following example shows the marker file for a successfully deployed instance of an
application called testappl i cati o n. war.
testappl i cati o n. war. d epl o yed
T ab le 10.1. Marker f ilet yp e d ef in it io n s

Filen ame Su f f ix
O rig in
D escrip t io n
. d o d epl o y
User generated
. ski pd epl o y
User generated
. i sd epl o yi ng
System generated
. d epl o yed
System generated
. fai l ed
System generated
. i sund epl o yi
ng
System generated
. und epl o yed
System generated
. pend i ng
System generated
Indicates that the content should be deployed or

redeployed into the runtime.
D isables auto-deploy of an application while present.
Useful as a method of temporarily blocking the autodeployment 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.
Indicates the initiation of deployment. The marker file will
be deleted when the deployment process completes.
Indicates that the content has been deployed. The content
will be undeployed if this file is deleted.
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.
Indicates a response to a . d epl o yed file deletion. The
content will be undeployed and the marker will be
automatically deleted upon completion.
Indicates that the content has been undeployed. D eletion
of the marker file has no impact to content redeployment.
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.
Report a bug
10.5.6. Reference for Deployment Scanner At t ribut es

The deployment scanner contains the following attributes that are exposed to the Management CLI
and able to be configured using the wri te-attri bute operation. For more information on
configuration options, refer to the topic Section 10.5.8, Configure the D eployment Scanner with the
Management CLI .
T ab le 10.2. D ep lo ymen t Scan n er At t rib u t es
N ame
D escrip t io n
T yp e
D ef au lt
Valu e
213
N ame
D escrip t io n
T yp e
D ef au lt
Valu e
auto -d epl o yexpl o d ed
Allows the automatic deployment of

exploded content without requiring a
. d o d epl o y marker file. Recommended
for only basic development scenarios to
prevent exploded application deployment
from occurring during changes by the
developer or operating system.
Allows the automatic deployment of XML
content without requiring a . d o d epl o y
marker file.
Allows the automatic deployment of
zipped content without requiring a
. d o d epl o y marker file.
The time value in seconds for the
deployment scanner to allow a
deployment attempt before being
cancelled.
D efines the actual filesystem path to be
scanned. If the rel ati ve-to attribute is
specified, the path value acts as a
relative addition to that directory or path.
Reference to a filesystem path defined in
the paths section of the server
configuration XML file.
Allows the automatic scanning for
applications by scan-i nterval and at
startup.
The time interval in milliseconds between
scans of the repository. A value of less
than 1 restricts the scanner to operate
only at startup.
Boolean
False
Boolean
True
Boolean
True
Long
600
String
deployment
s
String
jboss.server
.base.dir
Boolean
True
Int
5000
auto -d epl o y-xml
auto -d epl o y-zi pped
d epl o yment-ti meo ut
path
rel ati ve-to
scan-enabl ed
scan-i nterval
Report a bug
10.5.7. Configure t he 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.
Report a bug
10.5.8. Configure t he Deployment Scanner wit h t he Management CLI

Prereq u isit es
Su mmary
While there are multiple methods of configuring the deployment scanner, the Management CLI can be
214
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 -attri bute and wri te-attri bute global
command line operations. Further information about the deployment scanner attributes are defined in
the topic Section 10.5.6, Reference for D eployment Scanner Attributes .
The deployment scanner is a subsystem of JBoss EAP 6, and can be viewed in the
stand al o ne. xml .
Examp le 10.7. Excerp t f ro m stand al o ne. xml

<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
<deployment-scanner path="deployments" relativeto="jboss.server.base.dir" scan-interval="5000"/>
</subsystem>
Pro ced u re 10.12. C o n f ig u re t h e D ep lo ymen t Scan n er

1. D et ermin e t h e d ep lo ymen t scan n er at t rib u t es t o co n f ig u re
Configuring the deployment scanner via the Management CLI requires that you first expose
the correct attribute names. You can do this with the read -reso urces 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 l s command at this level.
A. Exp o se t h e d ep lo ymen t scan n er at t rib u t es wit h t h e read -reso urce o p erat io n
Use the read -reso urce operation to expose the attributes defined by the default
deployment scanner resource.
Examp le 10.8. Samp le read -reso urce o u t p u t

[standalone@ localhost:9999 /]/subsystem=deploymentscanner/scanner=default:read-resource
{
"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
}
}
B. Exp o se t h e d ep lo ymen t scan n er at t rib u t es wit h t h e l s co mman d

Use the l s 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 l s
command and its arguments by exposing the CLI help entry by typing l s --hel p. For
215
more information about the help menu in the Management CLI, refer to the topic
Section 3.4.5, Obtain Help with the Management CLI .
Examp le 10.9 . Samp le l s -l o u t p u t

[standalone@ localhost:9999 /] ls -l /subsystem=deploymentscanner/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. C o n f ig u re t h e d ep lo ymen t scan n er wit h t h e wri te-attri bute o p erat io n

Once you have determined the name of the attribute to modify, use the wri te-attri bute 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=deploymentscanner/scanner=default
a. En ab le au t o mat ic d ep lo ymen t o f exp lo d ed co n t en t
Use the wri te-attri bute operation to enable the automatic deployment of
exploded application content.
[standalone@ localhost:9999 scanner=default] :writeattribute(name=auto-deploy-exploded,value=true)
b. D isab le t h e au t o mat ic d ep lo ymen t o f XML co n t en t
Use the wri te-attri bute operation to disable the automatic deployment of XML
application content.
[standalone@ localhost:9999 scanner=default] :writeattribute(name=auto-deploy-xml,value=false)
c. D isab le t h e au t o mat ic d ep lo ymen t o f z ip p ed co n t en t
Use the wri te-attri bute command to disable the automatic deployment of zipped
application content.
216
[standalone@ localhost:9999 scanner=default] :writeattribute(name=auto-deploy-zipped,value=false)

d. C o n f ig u re t h e p at h at t rib u t e
Use the wri te-attri bute 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] :writeattribute(name=path,value=newpathname)
{
"response-headers" => {
"operation-requires-reload" => true,
"process-state" => "reload-required"
}
}
e. C o n f ig u re t h e relat ive p at h at t rib u t e
Use the wri te-attri bute 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] :writeattribute(name=relative-to,value=new.relative.dir)
{
}
}
f. D isab le t h e d ep lo ymen t scan n er
Use the wri te-attri bute operation to disable the deployment scanner by setting
the scan-enabl ed value to false.
[standalone@ localhost:9999 scanner=default] :writeattribute(name=scan-enabled,value=false)
g. C h an g e t h e scan in t erval
Use the wri te-attri bute operation to modify the scan interval time from 5000
milliseconds to 10000 milliseconds.
[standalone@ localhost:9999 scanner=default] :writeattribute(name=scan-interval,value=10000)
217
R esu lt
Your configuration changes are saved to the deployment scanner.
Report a bug
10.5.9. Define a Cust om Deployment Scanner

Prereq u isit es
Su mmary
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/stand al o ne/d epl o yments/. See Section 10.5.8, Configure the D eployment Scanner
with the Management CLI for details on configuring an existing deployment scanner.
Pro ced u re 10.13. D ef in e a C u st o m D ep lo ymen t Scan n er wit h t h e Man ag emen t C LI
1. Add a deployment scanner using the Management CLI ad d operation:
[standalone@ localhost:9999 /] /subsystem=deploymentscanner/scanner=new-scanner:add(path=new_deployment_dir,relativeto=jboss.server.base.dir,scan-interval=5000)
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 stand al o ne. xml file and management
interfaces.
Examp le 10.10. Excerp t f ro m stand al o ne. xml
<subsystem xmlns="urn:jboss:domain:deployment-scanner:1.1">
<deployment-scanner path="deployments" relativeto="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, D eploy an
Application to a Standalone Server Instance with the D eployment Scanner for details on
deploying an application with the deployment scanner.
R esu lt
A new deployment scanner has been defined and is monitoring for deployments.
218
Report a bug
10.6. Deploy wit h Maven

10.6.1. Manage Applicat ion Deployment wit h Maven
D eploying applications via Maven allows you to incorporate a deployment cycle as part of your
existing development workflow.
Report a bug
10.6.2. Deploy an Applicat ion wit h Maven

Prereq u isit es
Su mmary
This task shows a method for deploying applications with Maven. The example provided uses the
jbo ss-hel l o wo rl d . war application found in the JBoss EAP 6 Quickstarts collection. The
hel l o wo rl d project contains a POM file which initializes the jbo ss-as-maven-pl ug i n. This
plug-in provides simple operations to deploy and undeploy applications to and from the application
server.
Pro ced u re 10.14 . D ep lo y an ap p licat io n wit h Maven
1. Open a terminal session and navigate to the directory containing the quickstart examples.
Examp le 10.11. C h an g e in t o t h e h ello wo rld ap p licat io n d irect o ry

[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.
A. The deployment can be confirmed by viewing the operation logs in the terminal window.
Examp le 10.12. Maven co n f irmat io n f o r h ello wo rld ap p licat io n
[INFO] ----------------------------------------------------------------------[INFO] BUILD SUCCESS

[INFO] ----------------------------------------------------------------------[INFO] Total time: 32.629s
219
[INFO] Finished at: Fri Mar 14 09:09:50 EDT 2014

[INFO] Final Memory: 23M/204M
[INFO] -----------------------------------------------------------------------
B. The deployment can also be confirmed in the status stream of the active application server
instance.
Examp le 10.13. Ap p licat io n server co n f irmat io n f o r h ello wo rld ap p licat io n

09:09:49,167 INFO [org.jboss.as.repository] (managementhandler-thread - 1) JBAS014900: Content added at location
/home/username/EAP_HOME/standalone/data/content/32/4b4ef9a4bbe
7206d3674a89807203a2092fc70/content
09:09:49,175 INFO [org.jboss.as.server.deployment] (MSC
service thread 1-7) JBAS015876: Starting deployment of "jbosshelloworld.war" (runtime-name: "jboss-helloworld.war")
09:09:49,563 INFO [org.jboss.weld.deployer] (MSC service
thread 1-8) JBAS016002: Processing weld deployment jbosshelloworld.war
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)
thread 1-2) JBAS016008: Starting weld service for deployment
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-handlerthread - 1) JBAS018559: Deployed "jboss-helloworld.war"
(runtime-name : "jboss-helloworld.war")
R esu lt
The application is deployed to the application server.
Report a bug
10.6.3. Undeploy an Applicat ion wit h Maven

Prereq u isit es
Su mmary
This task shows a method for undeploying applications with Maven. The example provided uses the
jbo ss-hel l o wo rl d . war application found in the JBoss EAP 6 Quickstarts collection. The
hel l o wo rl d project contains a POM file which initializes the jbo ss-as-maven-pl ug i n. This
plug-in provides simple operations to deploy and undeploy applications to and from the application
server.
220
Pro ced u re 10.15. U n d ep lo y an Ap p licat io n wit h Maven

1. Open a terminal session and navigate to the directory containing the quickstart examples.
Examp le 10.14 . C h an g e in t o t h e h ello wo rld ap p licat io n d irect o ry

[localhost]$ cd /QUICKSTART_HOME/helloworld
2. Run the Maven undeploy command to undeploy the application.

[localhost]$ mvn jboss-as:undeploy
3. View the results.
A. The undeployment can be confirmed by viewing the operation logs in the terminal window.
Examp le 10.15. Maven co n f irmat io n f o r u n d ep lo y o f h ello wo rld ap p licat io n

[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] -----------------------------------------------------------------------
B. The undeployment can also be confirmed in the status stream of the active application
server instance.
Examp le 10.16 . Ap p licat io n server co n f irmat io n f o r u n d ep lo y o f h ello wo rld

ap p licat io n
09:51:40,512 INFO [org.jboss.web] (ServerService Thread Pool - 69) JBAS018224: Unregister web context: /jboss-helloworld
thread 1-3) JBAS016009: Stopping weld service for deployment
09:51:40,536 INFO [org.jboss.as.server.deployment] (MSC
service thread 1-1) JBAS015877: Stopped deployment jbosshelloworld.war (runtime-name: jboss-helloworld.war) in 27ms
09:51:40,621 INFO [org.jboss.as.repository] (managementhandler-thread - 10) JBAS014901: Content removed from location
/home/username/EAP_HOME/jboss-eap6.4/standalone/data/content/44/e1f3c55c84b777b0fc201d69451223c0
221
9c9da5/content
09:51:40,621 INFO [org.jboss.as.server] (management-handlerthread - 10) JBAS018558: Undeployed "jboss-helloworld.war"
(runtime-name: "jboss-helloworld.war")
R esu lt
The application is undeployed from the application server.
Report a bug
10.7. Cont rol t he order of Deployed Applicat ions 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.
Pro ced u re 10.16 . C o n t ro l t h e o rd er o f d ep lo ymen t 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.
Pro ced u re 10.17. C o n t ro l t h e o rd er o f d ep lo ymen t in EAP 6 .1 an d lat er
From EAP 6.1 onward, Inter D eployment D ependencies allows you to declare dependencies between
top level deployments.
1. Create (if it doesn't exist) a jbo ss-al l . xml file in the app. ear/MET A-INF folder, where
app. ear is the application archive that depends on another application archive to be
deployed before it is.
2. Make a jbo ss-d epl o yment-d epend enci es entry in this file as shown below. Note that in
the listing below, framewo rk. 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:deploymentdependencies:1.0">
<dependency name="framework.ear" />
</jboss-deployment-dependencies>
</jboss>
Report a bug
10.8. Define a Cust om Direct ory for Deployed Cont ent

JBoss EAP provides the option to define the location that the server will use for storing deployed
content.
222
D ef in e a C u st o m D irect o ry f o r D ep lo yed C o n t en t in St an d alo n e Mo d e

By default, deployed content in Standalone Mode is stored in the
EAP_HOME/stand al o ne/d ata/co ntent directory.
This location can be changed by passing in the -D jbo ss. server. d epl o y. d i r 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
jbo ss. server. d epl o y. d i r 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, D efine
a Custom D eployment Scanner .
D ef in e a C u st o m D irect o ry f o r D ep lo yed C o n t en t in D o main Mo d e

By default, deployed content in D omain Mode is stored in the EAP_HOME/d o mai n/d ata/co ntent
directory.
This location can be changed by passing in the -D jbo ss. d o mai n. d epl o yment. d i r
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.
Report a bug
10.9. Deployment Descript or 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.
Pro ced u re 10.18. O verrid e t h e d ep lo ymen t d escrip t o r u sin g t h e Man ag emen t C LI
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
/ho me/user/web. xml .
1. Add a deployment overlay and add content to it. You can achieve this in the following two
ways:
A. U sin g D MR t ree
223
a.
/d epl o yment-o verl ay= myo verl ay: ad d
b.
/d epl o yment-o verl ay= myo verl ay/co ntent= WEBINF\/web. xml : ad d (co ntent= {url = fi l e: ///ho me/user/web. xml })
You can also add more content rules using the second statement.
B. U sin g co n ven ien ce met h o d s

d epl o yment-o verl ay ad d --name= myo verl ay --co ntent= WEBINF/web. xml = /ho me/user/web. xml
2. Link the overlay to a deployment archive. You can achieve this in the following two ways:
A. U sin g D MR t ree
/d epl o yment-o verl ay= myo verl ay/d epl o yment= app. war: ad d
B. U sin g co n ven ien ce met h o d s
d epl o yment-o verl ay l i nk --name= myo verl ay --d epl o yments= 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. R ed ep lo y t h e ap p licat io n
/d epl o yment= app. war: red epl o y
Report a bug
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.
Examp le 10.17. C LI f o rmat o f a ro llo u t p lan

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 := '^'
224
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
ro l l o ut-pl an command.
Examp le 10.18. R o llo u t p lan man ag ed wit h t h e ro l l o ut-pl an co mman d

rollout-plan add --name=my-plan --content={rollout main-servergroupôther-server-group}
:write-attribute(name=my-attr,value=my-value){rollout id=my-plan}
Examp le 10.19 . U sin g a st o red ro llo u t p lan

rollout-plan add --name=my-plan --content={rollout main-servergroupôther-server-group}
:write-attribute(name=my-attr,value=my-value){rollout id=my-plan}
Report a bug
10.10.2. Operat ions wit h a Rollout Plan

The structure is of ro l l o ut-pl an within an o perati o n 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
}
225
},
{
"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 ro l l o ut-pl an is nested within the o perati o n-head ers structure. The root node of the
structure allows two children:
i n-seri es - 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.
ro l l back-acro ss-g ro ups - 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 i n-seri es node must have one or the other of the following
structures:
co ncurrent-g ro ups - 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-g ro up - 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 " concurrentgroups" 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:
ro l l i ng -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-fai l ed -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.
226
max-fai l ure-percentag e - 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-failurepercentage 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.
D ef au lt R o llo u t 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.
Report a bug
10.10.3. Creat ing 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 --runtimename=ClusterWebApp.war --server-groups=ha-server-group --headers=
{rollout ha-server-group(rolling-to-servers=true)}
227
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 --servergroups=main-server-group,other-server-group --headers={rollout
main-server-group(rolling-to-servers=true),other-servergroup(rolling-to-servers=true)}
Report a bug
228
Chapter 11. Subsystem Configuration

11.1. Subsyst em Configurat ion Overview
In t ro d u ct io n
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/d o mai n/co nfi g urati o n/d o mai n. xml for a managed
domain or EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne. xml for a standalone server.
Many of the subsystems include configuration details that were configured via deployment
descriptors in previous versions of JBoss EAP.
Su b syst em C o n f ig u rat io n Sch emas
Each subsystem's configuration is defined in an XML schema. The configuration schemas are
located in the EAP_HOME/d o cs/schema/ directory of your installation.
Report a bug
229
Chapter 12. The Logging Subsystem

12.1. Int roduct ion
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.
Report a bug
12.1.2. Applicat ion Logging Frameworks Support ed By JBoss LogManager

JBoss LogManager supports the following logging frameworks:
JBoss Logging - included with JBoss EAP 6
Apache Commons Logging - http://commons.apache.org/logging/
Simple Logging Facade for Java (SLF4J) - http://www.slf4j.org/
Apache log4j - http://logging.apache.org/log4j/1.2/
Java SE Logging (java.util.logging) http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html
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
230
Chapt er 1 2 . T he Logging Subsyst em
Note
If you are using the Lo g 4 j AP I and a Lo g 4 J Append er, then Objects will be converted to
stri ng before being passed.
Report a bug
12.1.3. Boot up Logging

D uring 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. l o g , the location of which depends on the runtime mode.
St an d alo n e mo d e
EAP_HOME/stand al o ne/l o g /server. l o g
D o main mo d e
EAP_HOME/d o mai n/servers/SERVER_NAME/l o g /server. l o g
The configuration of bootup logging is specified in the configuration file l o g g i ng . pro perti es,
the location of which depends on the runtime mode.
St an d alo n e mo d e
EAP_HOME/stand al o ne/co nfi g urati o n/l o g g i ng . pro perti es
D o main mo d e
In domain mode there is a l o g g i ng . pro perti es file for the domain controller and each
server.
D omain controller: EAP_HOME/d o mai n/co nfi g urati o n/l o g g i ng . pro perti es
Server: EAP_HOME/d o mai n/servers/SERVER_NAME/d ata/l o g g i ng . pro perti es
The configuration file l o g g i ng . pro perti es is active until the logging subsystem is started and
takes over.
Warning
It is recommended that you do not directly edit the l o g g i ng . pro perti es 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 l o g g i ng . pro perti es file are overwritten on startup.
Report a bug
12.1.4 . View Boot up Errors

When troubleshooting JBoss EAP, checking for errors which occurred during bootup should be one
231
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. l o g 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 -bo o t-erro rs.
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.
Pro ced u re 12.1. Examin e server.lo g f o r Erro rs
1. Open the file server. l o g in a file viewer.
2. Navigate to the end of the file.
3. Search backward for the message identifier JBAS0 1589 9 , which marks the start of the latest
bootup sequence.
4. Search the log from that point onward for instances of ER R O R . Each instance will include a
description of the error and list the modules involved.
Examp le 12.1. Erro r D escrip t io n f ro m server. l o g

The following is an example error description from the server. l o g 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
Pro ced u re 12.2. List B o o t u p Erro rs via t h e Man ag emen t C LI

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 currentT i meMi l l i s(), which is the
difference, measured in milliseconds, between the current time and midnight, January 1, 1970
UTC(coordinated universal time).
Examp le 12.2. O u t p u t f ro m read -bo o t-erro rs C o mman d

{
232
"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"}
}]
}
Report a bug
12.1.5. About Garbage Collect ion 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 stand al o ne mode on all supported configurations except IBM Java development kit.
Logging is output to the file EAP_HOME/stand al o ne/l o g /g c. l o g . 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.
Report a bug
12.1.6. Implicit Logging API Dependencies

The JBoss EAP 6 logging subsystem has the ad d -l o g g i ng -api -d epend enci es 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 fal se, implicit logging API dependencies will not be added.
The ad d -l o g g i ng -api -d epend enci es attribute can be configured using the Management CLI.
For example:
/subsystem= l o g g i ng : wri te-attri bute(name= ad d -l o g g i ng -api -d epend enci es,
val ue= false)
Report a bug
12.1.7. Default Log File Locat ions
233
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
T ab le 12.1. D ef au lt Lo g File f o r a st an d alo n e server
Lo g File
D escrip t io n
EAP_HOME/stand al o ne/l o g /server. l o g
Server Log. Contains all server log messages,

including server startup messages.
Garbage collection log. Contains details of all
garbage collection.
EAP_HOME/stand al o ne/l o g /g c. l o g
T ab le 12.2. D ef au lt Lo g Files f o r a man ag ed d o main

Lo g File
D escrip t io n
EAP_HOME/d o mai n/l o g /ho stco ntro l l er. l o g
Host Controller boot log. Contains log

messages related to the startup of the host
controller.
Process controller boot log. Contains log
messages related to the startup of the process
controller.
The server log for the named server. Contains all
log messages for that server, including server
startup messages.
EAP_HOME/d o mai n/l o g /pro cessco ntro l l er. l o g

EAP_HOME/d o mai n/servers/SERVERNAME/l
o g /server. l o g
Report a bug
12.1.8. Filt er 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 fi l ter-spec specified for the root logger is not inherited by other loggers. Instead a
fi l ter-spec must be specified per handler.
T ab le 12.3. Filt er Exp ressio n s f o r Lo g g in g

Filt er T yp e
D escrip t io n
Paramet ers
Accept all log

messages
accept
D eny all log

messages
d eny
expressi o n
Accept
accept
D eny
d eny
234
Filt er T yp e
D escrip t io n
Paramet ers
Returns the
inverted value of
the filter
expression
Takes single filter expression as a

parameter
Returns
concatenated
value from
multiple filter
expressions.
Takes multiple filter expressions

delimited by commas
expressi o n
Not
no t[fi l ter expressi o n]
All
al l [fi l ter expressi o n]
Any
any[fi l ter expressi o n]
Level Change
l evel C hang e[l evel ]
Levels
l evel s[l evel s]
no t(match("JBAS"))
al l (match("JBAS"),match("WELD
"))
Returns one value Takes multiple filter expressions

from multiple filter delimited by commas
expressions.
any(match("JBAS"),match("WELD
"))
Modifies the log
record with the
specified level
Takes single string-based level as an

argument
Filters log
messages with a
level listed in the
list of levels
Takes multiple string-based levels

delimited by commas as argument
l evel C hang e("WAR N")
l evel s("D EBUG ","INFO ","WAR N"

,"ER R O R ")
235
Filt er T yp e
D escrip t io n
Paramet ers
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.
expressi o n
Level Range
l evel R ang e[mi nLevel ,maxLeve
l]
Examples are shown below.

l evel R ang e("D EBUG ","ER R O R
")
Minimum level must be greater than
D EBUG and the maximum level
must be less than ER R O R .
l evel R ang e["D EBUG ","ER R O R
")
or equal to D EBUG and the
maximum level must be less than
ER R O R .
l evel R ang e["INFO ","ER R O R "
]
or equal to INFO and the maximum
level must be less than or equal to
ER R O R .
Match (match["pattern"])
Substitute
(substi tute["pattern","repl ace
ment val ue"])
236
A regularexpression based
filter. The
unformatted
message is used
against the
pattern specified
in the expression.
A filter which
replaces the first
match to the
pattern with the
replacement value
Takes a regular expression as

argument
match("JBAS\d + ")
The first argument for the expression

is the pattern the second argument is
the replacement text
substi tute("JBAS","EAP ")
Filt er T yp e
D escrip t io n
Paramet ers
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
expressi o n
Substitute All
(substi tuteAl l ["pattern","repl
acement val ue"])
substi tuteAl l ("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 stri ng . Otherwise, it would be parsed as a l i st. An example of the correct format would
be:
[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=CONSOLE:write-attribute(name=filter-spec,
value="substituteAll(\"JBAS\"\,\"SABJ\")")
Report a bug
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): T R AC E, D EBUG , INFO , WAR N,
ER R O R and FAT AL.
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 WAR N will only record messages of the
levels WAR N, ER R O R and FAT AL.
Report a bug
12.1.10. Support ed Log Levels

T ab le 12.4 . Su p p o rt ed Lo g Levels
Lo g Level
Valu e
D escrip t io n
FINEST
FINER
TRACE
300
400
400
Use for messages that provide detailed information about the running
state of an application. Log messages of T R AC E are usually only captured
when debugging an application.
237
Lo g Level
Valu e
D escrip t io n
D EBUG
500
FINE
CONFIG
INFO
500
700
800
WARN
900
WARNING
ERROR
900
1000
SEVERE
FATAL
1000
1100
Use for messages that indicate the progress individual requests or

activities of an application. Log messages of D EBUG are usually only
captured when debugging an application.
Use for messages that indicate the overall progress of the application.
Often used for application startup, shutdown and other major lifecycle
events.
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.
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.
Use to indicate events that could cause critical service failure and
application shutdown and possibly cause JBoss EAP 6 to shutdown.
Report a bug
12.1.11. About Log Cat egories

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.
Report a bug
12.1.12. About t he 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. l o g . This file is sometimes referred to as the server
log.
Report a bug
12.1.13. About Log Handlers

Log handlers define how captured log messages are recorded. The available log handlers are:
C o nso l e, Fi l e, P eri o d i c, Si ze, Async, sysl o g , P eri o d i c Si ze and C usto m.
238
Note
A log handler must be added to at least one logger to be active.
Report a bug
12.1.14 . T ypes of Log Handlers

C o n so le
Console log handlers write log messages to either the host operating system's standard out
(std o ut) or standard error (std err) 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.
Perio d ic
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.
Siz e
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.
Perio d ic Siz e
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.
Asyn c
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.
C u st o m
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. uti l . l o g g i ng . Hand l er and be contained in a module.
syslo g
239
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.
Report a bug
12.1.15. About Log Format t ers

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. uti l . Fo rmatter
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
Report a bug
12.1.16. Log Format t er Synt ax

T ab le 12.5. Lo g Fo rmat t er Syn t ax
Symb o l
D escrip t io n
%c
%p
%P
%d
%r
%z
%k
%m
%s
%e
%E
%t
%n
%C
%F
%l
%L
%M
%x
%X
%%
The category of the logging event

The level of the log entry (info/debug/etc)
The localized level of the log entry
The current date/time (yyyy-MM-dd HH:mm:ss,SSS form)
The relative time (milliseconds since the log was initialized)
The time zone
A log resource key (used for localization of log messages)
The log message (including exception trace)
The simple log message (no exception trace)
The exception stack trace (no extended module information)
The exception stack trace (with extended module information)
The name of the current thread
A newline character
The class of the code calling the log method (slow)
The filename of the class calling the log method (slow)
The source location of the code calling the log method (slow)
The line number of the code calling the log method (slow)
The method of the code calling the log method (slow)
The Nested D iagnostic Context
The Message D iagnostic Context
A literal percent character (escaping)
Report a bug
12.2. Configure Logging in t he Management Console
24 0
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.
Pro ced u re 12.3. Access Lo g g in g co n f ig u rat io n
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.
A. St an d alo n e Server
Click on C o n f ig u rat io n , expand C o re in the Su b syst ems menu, and then click
Lo g g in g .
B. Man ag ed D o main
Click on C o n f ig u rat io n , select the profile to edit from the drop-down menu. Expand
C o re in the Su b syst ems menu, and then click Lo g g in g .
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.
Report a bug
12.3. Logging Configurat ion in t he CLI

Prereq u isit e
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
Report a bug
12.3.1. Configure t he Root Logger wit h t he CLI
24 1
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.
D isplay 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= l o g g i ng /l o g g i ng -pro fi l e= NAME/ instead of
/subsystem= l o g g i ng /.
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= l o g g i ng / with /pro fi l e= NAME/subsystem= l o g g i ng /.
Ad d a Lo g H an d ler t o t h e R o o t Lo g g er
Use the ad d -hand l er 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.
Examp le 12.3. R o o t Lo g g er ad d - h an d ler o p erat io n

[standalone@ localhost:9999 /] /subsystem=logging/rootlogger=ROOT:add-handler(name="FILE")
D isp lay t h e C o n t en t s o f t h e R o o t Lo g g er C o n f ig u rat io n
Use the read -reso urce operation with the following syntax.
/subsystem=logging/root-logger=ROOT:read-resource
Examp le 12.4 . R o o t Lo g g er read - reso u rce o p erat io n

[standalone@ localhost:9999 /] /subsystem=logging/rootlogger=ROOT:read-resource
{
"result" => {
"filter" => undefined,
24 2
"filter-spec" => undefined,

"handlers" => [
"CONSOLE",
"FILE"
],
"level" => "INFO"
}
}
Set t h e Lo g Level o f t h e R o o t Lo g g er
Use the wri te-attri bute 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")
Examp le 12.5. R o o t Lo g g er writ e- at t rib u t e o p erat io n t o set t h e lo g level

[standalone@ localhost:9999 /] /subsystem=logging/rootlogger=ROOT:write-attribute(name="level", value="DEBUG")
R emo ve a Lo g H an d ler f ro m t h e R o o t Lo g g er
Use the remo ve-hand l er with the following syntax, where HANDLER is the name of the log
handler to be removed.
/subsystem=logging/root-logger=ROOT:removehandler(name="HANDLER")
Examp le 12.6 . R emo ve a Lo g H an d ler

[standalone@ localhost:9999 /] /subsystem=logging/rootlogger=ROOT:remove-handler(name="FILE")
Report a bug
12.3.2. Configure a Log Cat egory in t he 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.
D isplay the configuration of a log category.
Set the log level.
Add log handlers to a log category.
24 3
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
Ad d a lo g cat eg o ry
Use the ad d operation with the following syntax. Replace CATEGORY with the category to
be added.
/subsystem=logging/logger=CATEGORY:add
Examp le 12.7. Ad d in g a n ew lo g cat eg o ry

[standalone@ localhost:9999 /]
/subsystem=logging/logger=com.company.accounts.rec:add
D isp lay a lo g cat eg o ry co n f ig u rat io n
Use the read -reso urce operation with the following syntax. Replace CATEGORY with the
name of the category.
/subsystem=logging/logger=CATEGORY:read-resource
Examp le 12.8. Lo g C at eg o ry read - reso u rce o p erat io n

/subsystem=logging/logger=org.apache.tomcat.util.modeler:readresource
{
"result" => {
"category" => "org.apache.tomcat.util.modeler",
"handlers" => undefined,
"level" => "WARN",
"use-parent-handlers" => true
}
}
24 4
Set t h e lo g level
Use the wri te-attri bute 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")
Examp le 12.9 . Set t in g a lo g level

/subsystem=logging/logger=com.company.accounts.rec:writeattribute(name="level", value="DEBUG")
Set t h e lo g cat eg o ry t o u se t h e lo g h an d lers o f t h e ro o t lo g g er.
Use the wri te-attri bute 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="useparent-handlers", value="BOOLEAN")
Examp le 12.10. Set t in g u se- p aren t - h an d lers

/subsystem=logging/logger=com.company.accounts.rec:writeattribute(name="use-parent-handlers", value="true")
Ad d a lo g h an d lers t o a lo g cat eg o ry
Use the ad d -hand l er 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.
Examp le 12.11. Ad d in g a lo g h an d ler

/subsystem=logging/logger=com.company.accounts.rec:addhandler(name="AccountsNFSAsync")
R emo ve a lo g h an d ler f ro m a lo g cat eg o ry
24 5
Use the remo ve-hand l er 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")
Examp le 12.12. R emo vin g a lo g h an d ler

/subsystem=logging/logger=jacorb:removehandler(name="AccountsNFSAsync")
R emo ve a cat eg o ry
Use the remo ve operation with the following syntax. Replace CATEGORY with the name of
the category to be removed.
/subsystem=logging/logger=CATEGORY:remove
Examp le 12.13. R emo vin g a lo g cat eg o ry

/subsystem=logging/logger=com.company.accounts.rec:remove
Report a bug
12.3.3. Configure a Console Log Handler in t he 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.
D isplay 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.
24 6
Important
When configuring a log handler in a logging profile for a standalone system, the root of the
Ad d a C o n so le Lo g H an d ler
Use the ad d operation with the following syntax. Replace HANDLER with the console log
handler to be added.
/subsystem=logging/console-handler=HANDLER:add
Examp le 12.14 . Ad d a C o n so le Lo g H an d ler

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=ERRORCONSOLE:add
D isp lay a co n so le lo g h an d ler co n f ig u rat io n
Use the read -reso urce operation with the following syntax. Replace HANDLER with the
name of the console log handler.
/subsystem=logging/console-handler=HANDLER:read-resource
Examp le 12.15. D isp lay a co n so le lo g h an d ler co n f ig u rat io n

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=CONSOLE:read-resource
{
"result" => {
"autoflush" => true,
"enabled" => true,
"encoding" => undefined,
"formatter" => "%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n",
"level" => "INFO",
"name" => "CONSOLE",
"named-formatter" => "COLOR-PATTERN",
"target" => "System.out"
}
}
24 7
Set t h e Lo g Level
Use the wri te-attri bute 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:writeattribute(name="level", value="INFO")
Examp le 12.16 . Set t h e Lo g Level

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=ERRORCONSOLE:write-attribute(name="level",
value="TRACE")
Set t h e T arg et
name of the console log handler. Replace TARGET with either System. err or System. o ut
for the system error stream or standard out stream respectively.
/subsystem=logging/console-handler=HANDLER:writeattribute(name="target", value="TARGET")
Examp le 12.17. Set t h e T arg et

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=ERRORCONSOLE:write-attribute(name="target",
value="System.err")
Set t h e En co d in g
name of the console log handler. Replace ENCODING with the name of the required
character encoding system.
/subsystem=logging/console-handler=HANDLER:writeattribute(name="encoding", value="ENCODING")
Examp le 12.18. Set t h e En co d in g

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=ERRORCONSOLE:write-attribute(name="encoding",
value="utf-8")
Set t h e Fo rmat t er
name of the console log handler. Replace FORMAT with the required formatter string.
24 8
/subsystem=logging/console-handler=HANDLER:writeattribute(name="formatter", value="FORMAT")
Examp le 12.19 . Set t h e Fo rmat t er

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=ERRORCONSOLE:write-attribute(name="formatter",
value="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n")
Set t h e Au t o Flu sh
name of the console log handler. Replace BOOLEAN with true if this handler is to
immediately write its output.
/subsystem=logging/console-handler=HANDLER:writeattribute(name="autoflush", value="BOOLEAN")
Examp le 12.20. Set t h e Au t o Flu sh

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=ERRORCONSOLE:write-attribute(name="autoflush",
value="true")
R emo ve a C o n so le Lo g H an d ler
Use the remo ve operation with the following syntax. Replace HANDLER with the name of the
console log handler to be removed.
/subsystem=logging/console-handler=HANDLER:remove
Examp le 12.21. R emo ve a C o n so le Lo g H an d ler

[standalone@ localhost:9999 /] /subsystem=logging/consolehandler=ERRORCONSOLE:remove
Report a bug
12.3.4 . Configure a File Log Handler in t he 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.
D isplay the configuration of a file log handler
24 9

Set the handler's appending behavior.
Specify the file to which the log handler will write.
Remove a file log handler.
Important
Ad d a f ile lo g h an d ler
Use the ad d 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"})
Examp le 12.22. Ad d a f ile lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/filehandler=accounts_log:add(file={"path"=>"accounts.log",
"relative-to"=>"jboss.server.log.dir"})
D isp lay a f ile lo g h an d ler co n f ig u rat io n
Use the read -reso urce operation with the following syntax. Replace HANDLER with the
name of the file log handler.
/subsystem=logging/file-handler=HANDLER:read-resource
Examp le 12.23. U sin g t h e read - reso u rce o p erat io n

[standalone@ localhost:9999 /] /subsystem=logging/file-
250
handler=accounts_log:read-resource
{
"result" => {
"append" => true,
"enabled" => true,
"file" => {
"path" => "accounts.log",
"relative-to" => "jboss.server.log.dir"
},
"level" => "ALL",
"name" => "accounts_log",
"named-formatter" => undefined
}
}
Set t h e Lo g level
name of the file log handler. Replace LOG_LEVEL_VALUE with the log level that is to be set.
/subsystem=logging/file-handler=HANDLER:writeattribute(name="level", value="LOG_LEVEL_VALUE")
Examp le 12.24 . C h an g in g t h e lo g level

/subsystem=logging/file-handler=accounts_log:writeattribute(name="level", value="DEBUG")
Set t h e ap p en d b eh avio u r
name of the file log handler. Replace BOOLEAN with false if you required that a new log file
be created each time the application server is launched. Replace BOOLEAN with true if the
application server should continue to use the same file.
/subsystem=logging/file-handler=HANDLER:writeattribute(name="append", value="BOOLEAN")
Examp le 12.25. C h an g in g t h e ap p en d p ro p ert y

[standalone@ localhost:9999 /] /subsystem=logging/filehandler=accounts_log:write-attribute(name="append",
value="true")
{
251
}
}
JBoss EAP 6 must be restarted for this change to take effect.

name of the file log handler. Replace BOOLEAN with true if this handler is to immediately
write its output.
/subsystem=logging/file-handler=HANDLER:writeattribute(name="autoflush", value="BOOLEAN")
Examp le 12.26 . C h an g in g t h e au t o f lu sh p ro p ert y

[standalone@ localhost:9999 /] /subsystem=logging/filehandler=accounts_log:write-attribute(name="autoflush",
value="false")
name of the file log handler. Replace ENCODING with the name of the required character
encoding system.
/subsystem=logging/file-handler=HANDLER:writeattribute(name="encoding", value="ENCODING")
Examp le 12.27. Set t h e En co d in g

[standalone@ localhost:9999 /] /subsystem=logging/filehandler=accounts_log:write-attribute(name="encoding",
value="utf-8")
C h an g e t h e f ile t o wh ich t h e lo g h an d ler writ es
Use the wri te-attri bute 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:writeattribute(name="file", value={"path"=>"PATH", "relativeto"=>"DIR"})
252
Examp le 12.28. C h an g e t h e f ile t o wh ich t h e lo g h an d ler writ es

[standalone@ localhost:9999 /] /subsystem=logging/filehandler=accounts_log:write-attribute(name="file", value=
{"path"=>"accounts-debug.log", "relativeto"=>"jboss.server.log.dir"})
name of the file log handler. Replace FORMAT with the required formatter string.
/subsystem=logging/file-handler=HANDLER:writeattribute(name="formatter", value="FORMAT")
Examp le 12.29 . Set t h e Fo rmat t er

[standalone@ localhost:9999 /] /subsystem=logging/filehandler=accounts_log:write-attribute(name="formatter",
value="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n")
R emo ve a File Lo g H an d ler
Use the remo ve operation with the following syntax. Replace HANDLER with the name of the
file log handler to be removed.
/subsystem=logging/file-handler=HANDLER:remove
Examp le 12.30. R emo ve a File Lo g H an d ler

[standalone@ localhost:9999 /] /subsystem=logging/filehandler=accounts_log:remove
A log handler can only be removed if it is not being referenced by a log category or an
async log handler.
Report a bug
12.3.5. Configure a Periodic Log Handler in t he CLI

Periodic log handlers can be added, removed and edited in the CLI.
The main tasks you will perform to configure a periodic log handler are:
Add a new periodic log handler.
D isplay the configuration of a periodic log handler
253

Set whether or not the handler uses auto fl ush.
Set the suffix for rotated logs.
Remove a periodic log handler.
Each of those tasks are described below.
Important
Ad d a n ew Perio d ic R o t at in g File lo g h an d ler

Use the ad d operation with the following syntax.
/subsystem=logging/periodic-rotating-filehandler=HANDLER:add(file={"path"=>"PATH", "relative-to"=>"DIR"},
suffix="SUFFIX")
Replace HANDLER with the name of the log handler. 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. Replace SUFFIX with the file
rotation suffix to be used.
Examp le 12.31. Ad d a n ew h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:add(file={"path"=>"dailydebug.log", "relative-to"=>"jboss.server.log.dir"},
suffix=".yyyy.MM.dd")
D isp lay a Perio d ic R o t at in g File lo g h an d ler co n f ig u rat io n

254
/subsystem=logging/periodic-rotating-file-handler=HANDLER:readresource
Replace HANDLER with the name of the log handler.
Examp le 12.32. U sin g t h e read - reso u rce o p erat io n

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:read-resource
{
"result" => {
"append" => true,
"enabled" => true,
"file" => {
"path" => "daily-debug.log",
},
"level" => "ALL",
"name" => "HOURLY_DEBUG",
"named-formatter" => undefined,
"suffix" => ".yyyy.MM.dd"
},
"response-headers" => {"process-state" => "reload-required"}
}
Set t h e Lo g level
Use the wri te-attri bute operation with the following syntax.
/subsystem=logging/periodic-rotating-file-handler=HANDLER:writeattribute(name="level". value="LOG_LEVEL_VALUE")
Replace HANDLER with the name of the periodic log handler. Replace LOG_LEVEL_VALUE
with the log level that is to be set.
Examp le 12.33. Set t h e lo g level

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:writeattribute(name="level", value="DEBUG")
Set t h e ap p en d b eh avio r
255
/subsystem=logging/periodic-rotating-handler=HANDLER:writeattribute(name="append", value="BOOLEAN")
Replace HANDLER with the name of the periodic log handler. Replace BOOLEAN with
fal se if you required that a new log file be created each time the application server is
launched. Replace BOOLEAN with true if the application server should continue to use the
same file.
Examp le 12.34 . Set t h e ap p en d b eh avio r

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:writeattribute(name="append", value="true")
{
}
}
/subsystem=logging/periodic-rotating-file-handler=HANDLER:writeattribute(name="autoflush", value="BOOLEAN")
Replace HANDLER with the name of the periodic log handler. Replace BOOLEAN with true
if this handler is to immediately write its output.
Examp le 12.35. Set t h e Au t o Flu sh b eh avio r

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:writeattribute(name="autoflush", value="false")
{
}
/subsystem=logging/periodic-rotating-file-handler=HANDLER:writeattribute(name="encoding", value="ENCODING")
Replace HANDLER with the name of the periodic log handler. Replace ENCODING with the
name of the required character encoding system.
256
Examp le 12.36 . Set t h e En co d in g

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:writeattribute(name="encoding", value="utf-8")
C h an g e t h e f ile t o wh ich t h e lo g h an d ler writ es
/subsystem=logging/periodic-rotating-file-handler=HANDLER:writeattribute(name="file", value={"path"=>"PATH", "relativeto"=>"DIR"})
Replace HANDLER with the name of the periodic log handler. 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.
Examp le 12.37. C h an g e t h e f ile t o wh ich t h e lo g h an d ler writ es

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:write-attribute(name="file",
value={"path"=>"daily-debug.log", "relativeto"=>"jboss.server.log.dir"})
/subsystem=logging/periodic-rotating-file-handler=HANDLER:writeattribute(name="formatter", value="FORMAT")
Replace HANDLER with the name of the periodic log handler. Replace FORMAT with the
required formatter string.
Examp le 12.38. Set t h e Fo rmat t er

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:writeattribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p [%c]
(%t) %s%E%n")
Set t h e su f f ix f o r ro t at ed lo g s
/subsystem=logging/periodic-rotating-file-handler=HANDLER:writeattribute(name="suffix", value="SUFFIX")
257
Replace HANDLER with the name of the log handler. Replace SUFFIX with the required suffix
string.
Examp le 12.39 . Set t h e su f f ix f o r ro t at ed lo g

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:writeattribute(name="suffix", value=".yyyy-MM-dd-HH")
R emo ve a p erio d ic lo g h an d ler

Use the remo ve operation with the following syntax.
/subsystem=logging/periodic-rotating-file-handler=HANDLER:remove
Replace HANDLER with the name of the periodic log handler.
Examp le 12.4 0. R emo ve a p erio d ic lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/periodicrotating-file-handler=HOURLY_DEBUG:remove
Report a bug
12.3.6. Configure a Siz e Log Handler in t he CLI

Size rotated file log handlers can be added, removed and edited in the CLI.
The tasks you will perform to configure a size rotated file log handler are:
Add a new log handler.
D isplay the configuration of the log handler.
Set the maximum size of each log file.
Set the maximum number of backup logs to keep.
258
Set the rotate on boot option for the size rotation file handler.
Remove a log handler.
Each of these tasks are described below.
Important
Ad d a n ew lo g h an d ler
/subsystem=logging/size-rotating-file-handler=HANDLER:add(file=
{"path"=>"PATH", "relative-to"=>"DIR"})
is to be located. The value of DIR can be a path variable.
Examp le 12.4 1. Ad d a n ew lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:add(file=
{"path"=>"accounts_trace.log", "relativeto"=>"jboss.server.log.dir"})
D isp lay t h e co n f ig u rat io n o f t h e lo g h an d ler
/subsystem=logging/size-rotating-file-handler=HANDLER:readresource
Examp le 12.4 2. D isp lay t h e co n f ig u rat io n o f t h e lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:read-resource
{
259

"result" => {
"append" => true,
"enabled" => true,
"file" => {
"path" => "accounts_trace.log",
},
"level" => "ALL",
"max-backup-index" => 1,
"name" => "ACCOUNTS_TRACE",
"rotate-on-boot" => false,
"rotate-size" => "2m",
"suffix" => undefined
}
}
Set t h e h an d ler' s lo g level
/subsystem=logging/size-rotating-file-handler=HANDLER:writeattributel(name="level", value="LOG_LEVEL_VALUE")
Replace HANDLER with the name of the log handler. Replace LOG_LEVEL_VALUE with the
log level that is to be set.
Examp le 12.4 3. Set t h e h an d ler' s lo g level

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="level",
value="TRACE")
Set t h e h an d ler' s ap p en d in g b eh avio r

/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="append", value="BOOLEAN")
Replace HANDLER with the name of the log handler. Replace BOOLEAN with fal se if you
required that a new log file be created each time the application server is launched. Replace
BOOLEAN with true if the application server should continue to use the same file.
260
Examp le 12.4 4 . Set t h e h an d ler' s ap p en d in g b eh avio r

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="append",
value="true")
{
}
}
Set wh et h er t h e h an d ler u ses au t o f lu sh o r n o t

/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="autoflush", value="BOOLEAN")
Replace HANDLER with the name of the log handler. Replace BOOLEAN with true if this
handler is to immediately write its output.
Examp le 12.4 5. Set wh et h er t h e h an d ler u ses au t o f lu sh o r n o t

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="autoflush",
value="true")
Set t h e en co d in g u sed f o r t h e h an d ler' s o u t p u t

/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="encoding", value="ENCODING")
Replace HANDLER with the name of the log handler. Replace ENCODING with the name of
the required character encoding system.
Examp le 12.4 6 . Set t h e en co d in g u sed f o r t h e h an d ler' s o u t p u t

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="encoding",
value="utf-8")
Sp ecif y t h e f ile t o wh ich t h e lo g h an d ler will writ e
261
/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="file", value={"path"=>"PATH", "relativeto"=>"DIR"})

Examp le 12.4 7. Sp ecif y t h e f ile t o wh ich t h e lo g h an d ler will writ e

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="file", value=
{"path"=>"accounts_trace.log", "relativeto"=>"jboss.server.log.dir"})
Set t h e f o rmat t er u sed f o r t h e h an d ler' s o u t p u t
/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="formatter", value="FORMATTER")
Replace HANDLER with the name of the log handler. Replace FORMAT with the required
formatter string.
Examp le 12.4 8. Set t h e f o rmat t er u sed f o r t h e h an d ler' s o u t p u t

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="formatter",
value="%d{HH:mm:ss,SSS} %-5p (%c) [%t] %s%E%n")
Set t h e maximu m siz e o f each lo g f ile
/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="rotate-size", value="SIZE")
Replace HANDLER with the name of the log handler. Replace SIZE with maximum file size.
Examp le 12.4 9 . Set t h e maximu m siz e o f each lo g f ile

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="rotate-size",
value="50m")
Set t h e maximu m n u mb er o f b acku p lo g s t o keep
262
/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="max-backup-index", value="NUMBER")
Replace HANDLER with the name of the log handler. Replace NUMBER with the required
number of log files to keep.
Examp le 12.50. Set t h e maximu m n u mb er o f b acku p lo g s t o keep

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="max-backupindex", value="5")
Set t h e ro t at e- o n - b o o t o p t io n o n t h e si ze-ro tati ng -fi l e-hand l er

This option is only available for the si ze-ro tati ng -fi l e-hand l er file handler. It
defaults to fal se, meaning a new log file is not created on server restart.
To change it, use the wri te-attri bute operation with the following syntax.
/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="rotate-on-boot", value="BOOLEAN")
Replace HANDLER with the name of the si ze-ro tati ng -fi l e-hand l er log handler.
Replace BOOLEAN with true if a new si ze-ro tati ng -fi l e-hand l er log file should be
created on restart.
Examp le 12.51. Sp ecif y t o creat e a n ew si ze-ro tati ng -fi l e-hand l er lo g f ile

o n server rest art
[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="rotate-onboot", value="true")
/subsystem=logging/size-rotating-file-handler=HANDLER:writeattribute(name="suffix", value="SUFFIX")
string.
Examp le 12.52. Set t h e su f f ix f o r ro t at ed lo g s
263
[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:write-attribute(name="suffix",

value=".yyyy-MM-dd-HH")
R emo ve a lo g h an d ler
/subsystem=logging/size-rotating-file-handler=HANDLER:remove
Examp le 12.53. R emo ve a lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/size-rotatingfile-handler=ACCOUNTS_TRACE:remove
Report a bug
12.3.7. Configure a Periodic Siz e Rot at ing Log Handler in t he CLI

Periodic Size Rotating log handlers can be added, removed and edited in the CLI.
The main tasks you will perform to configure a periodic size rotating handler are:
Add a new periodic size rotating handler.
D isplay the configuration of a periodic size rotating handler.
Set whether or not the handler uses auto fl ush.
Set the maximum size of each log file.
Set the maximum number of backup logs to keep.
Set the rotate on boot option for the periodic size rotating handler.
Remove a periodic size rotating handler.
Each of those tasks are described below.
264
Important
When configuring a periodic size rotating handler in a logging profile for a standalone
system, the root of the configuration path is /subsystem= l o g g i ng /l o g g i ng pro fi l e= NAME/ instead of /subsystem= l o g g i ng /.
Ad d a n ew Perio d ic Siz e R o t at in g h an d ler

/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:add(file={"path"=>"PATH", "relative-to"=>"DIR"})
Examp le 12.54 . Ad d a n ew lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:add(file=
{"path"=>"periodic_size.log","relativeto"=>"jboss.server.log.dir"},suffix=".yyyy.MM.dd")
D isp lay t h e co n f ig u rat io n o f t h e lo g h an d ler
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:read-resource
Examp le 12.55. D isp lay t h e co n f ig u rat io n o f t h e lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:read-resource
{
"result" => {
"append" => true,
"enabled" => true,
"file" => {
"relative-to" => "jboss.server.log.dir",
265
"path" => "periodic_size.log"

},
"level" => "ALL",
"max-backup-index" => 1,
"name" => "PERIODIC_SIZE",
"rotate-on-boot" => false,
"rotate-size" => "2m",
"suffix" => ".yyyy.MM.dd"
}
}
Set t h e h an d ler' s lo g level

/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="level",
value="LOG_LEVEL_VALUE")
Examp le 12.56 . Set t h e h an d ler' s lo g level

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="level", value="TRACE")
Set t h e h an d ler' s ap p en d in g b eh avio r

/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="append", value="BOOLEAN")
Replace HANDLER with the name of the log handler. Replace BOOLEAN with fal se if you
required that a new log file be created each time the application server is launched. Replace
BOOLEAN with true if the application server should continue to use the same file.
Examp le 12.57. Set t h e h an d ler' s ap p en d in g b eh avio r

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="append", value="true")
{
266

}
}
Set wh et h er t h e h an d ler u ses au t o f lu sh o r n o t

/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="autoflush",
value="BOOLEAN")
Replace HANDLER with the name of the log handler. Replace BOOLEAN with true if this
handler is to immediately write its output.
Examp le 12.58. Set wh et h er t h e h an d ler u ses au t o f lu sh o r n o t

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="autoflush", value="true")
Set t h e en co d in g u sed f o r t h e h an d ler' s o u t p u t

/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="encoding",
value="ENCODING")
Replace HANDLER with the name of the log handler. Replace ENCODING with the name of
the required character encoding system.
Examp le 12.59 . Set t h e en co d in g u sed f o r t h e h an d ler' s o u t p u t

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="encoding", value="utf-8")
Sp ecif y t h e f ile t o wh ich t h e lo g h an d ler will writ e
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="file", value=
{"path"=>"PATH", "relative-to"=>"DIR"})
267
Examp le 12.6 0. Sp ecif y t h e f ile t o wh ich t h e lo g h an d ler will writ e

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="file", value={"path"=>"accounts_trace.log",
Set t h e f o rmat t er u sed f o r t h e h an d ler' s o u t p u t
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="formatter", value="FORMAT")
Replace HANDLER with the name of the log handler. Replace FORMAT with the required
formatter string or name of the formatter as specified in the configuration file.
Examp le 12.6 1. Set t h e f o rmat t er u sed f o r t h e h an d ler' s o u t p u t

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="formatter", value="%d{HH:mm:ss,SSS} %-5p (%c)
[%t] %s%E%n")
Set t h e maximu m siz e o f each lo g f ile
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="rotate-size", value="SIZE")
Replace HANDLER with the name of the log handler. Replace SIZE with maximum file size.
Examp le 12.6 2. Set t h e maximu m siz e o f each lo g f ile

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="rotate-size", value="50m")
Set t h e maximu m n u mb er o f b acku p lo g s t o keep

268
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="max-backup-index",
value="NUMBER")
Replace HANDLER with the name of the log handler. Replace NUMBER with the required
number of log files to keep.
Examp le 12.6 3. Set t h e maximu m n u mb er o f b acku p lo g s t o keep

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:write-attribute(name="maxbackup-index", value="5")
Set t h e ro t at e- o n - b o o t o p t io n o n t h e peri o d i c-si ze-ro tati ng -fi l e-hand l er

It defaults to fal se, meaning a new log file is not created on server restart.
To change it, use the wri te-attri bute operation with the following syntax.
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="rotate-on-boot",
value="BOOLEAN")
Replace HANDLER with the name of the peri o d i c-si ze-ro tati ng -fi l e-hand l er log
handler. Replace BOOLEAN with true if a new peri o d i c-si ze-ro tati ng -fi l ehand l er log file should be created on restart.
Examp le 12.6 4 . Sp ecif y t o creat e a n ew peri o d i c-si ze-ro tati ng -fi l ehand l er lo g f ile o n server rest art
[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:writeattribute(name="rotate-on-boot", value="true")
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:write-attribute(name="suffix", value="SUFFIX")
string.
Examp le 12.6 5. Set a su f f ix f o r ro t at ed lo g s

[standalone@ localhost:9999 /] /subsystem=logging/periodic-size-
269
rotating-file-handler=PERIODIC_SIZE:writeattribute(name="suffix", value=".yyyy-MM-dd-HH")
R emo ve a lo g h an d ler
/subsystem=logging/periodic-size-rotating-filehandler=HANDLER:remove
Examp le 12.6 6 . R emo ve a lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/periodic-sizerotating-file-handler=PERIODIC_SIZE:remove
Report a bug
12.3.8. Configure a Async Log Handler in t he CLI

Async log handlers can be added, removed and edited in the CLI.
The tasks you will perform to configure an async log handler are:
Add a new async log handler
D isplay the configuration of an async log handler
Change the log level
Set the queue length
Set the overflow action
Add sub-handlers
Remove sub-handlers
Remove an async log handler
Each of these tasks are described below.
270
Important
Ad d a n ew asyn c lo g h an d ler
/subsystem=logging/async-handler=HANDLER:add(queuelength="LENGTH")
Replace HANDLER with the name of the log handler. Replace LENGTH with value of the
maximum number of log requests that can be held in queue.
Examp le 12.6 7. Ad d a n ew asyn c lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:add(queue-length="10")
D isp lay t h e co n f ig u rat io n o f an asyn c lo g h an d ler
/subsystem=logging/async-handler=HANDLER:read-resource
Examp le 12.6 8. D isp lay t h e co n f ig u rat io n o f an asyn c lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:read-resource
{
"result" => {
"enabled" => true,
"level" => "ALL",
"name" => "NFS_LOGS",
"overflow-action" => "BLOCK",
"queue-length" => "10",
271
"subhandlers" => undefined

},
}
C h an g e t h e lo g level
/subsystem=logging/async-handler=HANDLER:writeattribute(name="level", value="LOG_LEVEL_VALUE")
Examp le 12.6 9 . C h an g e t h e lo g level

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:write-attribute(name="level", value="INFO")
Set t h e q u eu e len g t h
/subsystem=logging/async-handler=HANDLER:writeattribute(name="queue-length", value="LENGTH")
Replace HANDLER with the name of the log handler. Replace LENGTH with value of the
maximum number of log requests that can be held in queue.
Examp le 12.70. Set t h e q u eu e len g t h

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:write-attribute(name="queue-length",
value="150")
{
}
}
Set t h e o verf lo w act io n
/subsystem=logging/async-handler=HANDLER:writeattribute(name="overflow-action", value="ACTION")
272
Replace HANDLER with the name of the log handler. Replace ACTION with either DISCARD
or BLOCK.
Examp le 12.71. Set t h e o verf lo w act io n

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:write-attribute(name="overflow-action",
value="DISCARD")
Ad d su b - h an d lers
Use the ad d -hand l er operation with the following syntax.
/subsystem=logging/async-handler=HANDLER:addhandler(name="SUBHANDLER")
Replace HANDLER with the name of the log handler. Replace SUBHANDLER with the name
of the log handler that is to be added as a sub-handler of this async handler.
Examp le 12.72. Ad d su b - h an d lers

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:add-handler(name="NFS_FILE")
R emo ve su b - h an d lers
Use the remo ve-hand l er operation with the following syntax.
/subsystem=logging/async-handler=HANDLER:removehandler(name="SUBHANDLER")
Replace HANDLER with the name of the log handler. Replace SUBHANDLER with the name
of the sub-handler to remove.
Examp le 12.73. R emo ve su b - h an d lers

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:remove-handler(name="NFS_FILE")
R emo ve an asyn c lo g h an d ler

/subsystem=logging/async-handler=HANDLER:remove
273
Examp le 12.74 . R emo ve an asyn c lo g h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/asynchandler=NFS_LOGS:remove
Report a bug
12.3.9. Configure a Cust om Handler in t he CLI

Custom handler can be added, removed, and edited in the CLI.
The main tasks you will perform to configure a custom handler are:
Add a new custom handler.
D isplay the configuration of a custom handler.
Set the log level.
Remove a custom handler.
Important
When configuring a custom handler in a logging profile for a standalone system, the root of
the configuration path is /subsystem= l o g g i ng /l o g g i ng -pro fi l e= NAME/ instead of
Ad d a N ew C u st o m H an d ler
/subsystem=logging/custom-handler="MyCustomHandler":add
Examp le 12.75. Ad d in g a n ew cu st o m h an d ler

[standalone@ localhost:9999 /] /subsystem=logging/customhandler="MyCustomHandler":add(class="JdbcLogger",module="com.MyM
odule",formatter="%d{HH:mm:ss,SSS} %-5p [%c] (%t)
%s%E%n",properties=
{"maxNumberOfDays"=>"90","fileName"=>"custom.log","compressBacku
ps"=>"true"})
274
D isp lay C u st o m H an d ler

Use the read -reso urce operation with the following syntax. Replace CUSTOMHANDLER
with the name of the custom handler.
/subsystem=logging/custom-handler=CUSTOMHANDLER:read-resource
Examp le 12.76 . D isp lay a cu st o m h an d ler co n f ig u rat io n

[standalone@ localhost:9999 /] /subsystem=logging/customhandler="MyCustomHandler":read-resource
{
"result" => {
"enabled" => true,
"level" => "INFO",
"name" => "CONSOLE",
"named-formatter" => "COLOR-PATTERN",
"target" => "System.out"
}
}
Set t h e Lo g Level
Use the wri te-attri bute operation with the following syntax. Replace CUSTOMHANDLER
with the name of the log category and LEVEL with the log level that is to be set.
/subsystem=logging/custom-handler=CUSTOMHANDLER:writeattribute(name="level", value="INFO")
Examp le 12.77. Set t h e Lo g Level

[standalone@ localhost:9999 /] /subsystem=logging/customhandler="MyCustomHandler":write-attribute(name="level",
value="TRACE")
R emo ve C u st o m H an d ler
Use the remo ve operation with the following syntax. Replace CUSTOMHANDLER with the
name of the custom handler to be removed.
/subsystem=logging/custom-handler=CUSTOMHANDLER:remove
Examp le 12.78. R emo ve a cu st o m h an d ler
275
[standalone@ localhost:9999 /] /subsystem=logging/customhandler="MyCustomHandler":remove

Report a bug
12.3.10. Configure a Syslog Handler in t he CLI

The log manager for JBoss EAP 6 now contains a syslog handler. Syslog handlers can be used to
send messages to a remote logging server that supports the Sysl o g protocol (RFC-3164 or RFC5424). This allows the log messages of multiple applications to be sent to the same server, where they
can be parsed together. This topic covers how to create and configure a syslog handler using the
Management CLI, and the available configuration options.
For details of syslog handler attributes see Section A.3, Management Interface Audit Logging
Reference .
Prereq u isit es
Access and the correct permissions for the Management CLI.
Pro ced u re 12.4 . Ad d a Syslo g H an d ler
Run the following command to add a syslog handler:
/subsystem=logging/syslog-handler=HANDLER_NAME:add
Pro ced u re 12.5. C o n f ig u re a Syslo g H an d ler
Run the following command to configure a syslog handler attribute:
/subsystem=logging/syslog-handler=HANDLER_NAME:writeattribute(name=ATTRIBUTE_NAME,value=ATTRIBUTE_VALUE)
Pro ced u re 12.6 . R emo ve a Syslo g H an d ler
Run the following command to remove an existing syslog handler:
/subsystem=logging/syslog-handler=HANDLER_NAME:remove
Report a bug
12.3.11. Configure a Cust om Log Format t er in t he CLI

Su mmary
In addition to the log formatter syntax specified in Section 12.1.16, Log Formatter Syntax , a custom
log formatter can be created for use with any log handler. This example procedure will demonstrate
this by creating a XML formatter for a console log handler.
Prereq u isit es
276
Access to the Management CLI for the JBoss EAP 6 server.

A previously configured log handler. This example procedure uses a console log handler.
Pro ced u re 12.7. C o n f ig u re a C u st o m XML Fo rmat t er f o r a Lo g H an d ler
1. Create custom formatter.
In this example, the following command creates a custom formatter named XML_FO R MAT T ER
that uses the java. uti l . l o g g i ng . XMLFo rmatter class.
[standalone@ localhost:9999 /] /subsystem= l o g g i ng /custo mfo rmatter= XML_FO R MAT T ER : ad d (cl ass= java. uti l . l o g g i ng . XMLFo rmatter
, mo d ul e= o rg . jbo ss. l o g manag er)
2. Register a custom formatter for the log handler you want to use it with.
In this example, the formatter from the previous step is added to a console log handler.
[standalone@ localhost:9999 /] /subsystem= l o g g i ng /co nso l ehand l er= HANDLER: wri te-attri bute(name= named -fo rmatter,
val ue= XML_FO R MAT T ER )
3. Restart the JBoss EAP 6 server for the change to take effect.
[standalone@ localhost:9999 /] shutd o wn --restart= true
R esu lt
The custom XML formatter is added to the console log handler. Output to the console log will be
formatted in XML, for example:
<record>
<date>2014-03-11T13:02:53</date>
<millis>1394539373833</millis>
<sequence>116</sequence>
<logger>org.jboss.as</logger>
<level>INFO</level>
<class>org.jboss.as.server.BootstrapListener</class>
<method>logAdminConsole</method>
<thread>282</thread>
<message>JBAS015951: Admin console listening on http://%s:%d</message>
<param>127.0.0.1</param>
<param>9990</param>
</record>
Report a bug
12.4 . Per-deployment Logging

12.4 .1. About Per-deployment Logging
277
Per-deployment logging allows a developer to configure in advance the logging configuration for
their application. When the application is deployed, logging begins according to the defined
configuration. The log files created through this configuration contain information only about the
behavior of the application.
This approach has advantages and disadvantages over using system-wide logging. An advantage
is that the administrator of the JBoss EAP instance does not need to configure logging. A
disadvantage is that the per-deployment logging configuration is read only on startup and so
cannot be changed at runtime.
Report a bug
12.4 .2. Disable Per-deployment Logging

Pro ced u re 12.8. D isab le Per- d ep lo ymen t Lo g g in g
T wo met h o d s o f d isab lin g p er- d ep lo ymen t lo g g in g are availab le. O n e wo rks o n all
versio n s o f JB o ss EAP 6 , wh ile t h e o t h er wo rks o n ly o n JB o ss EAP 6 .3 an d h ig h er.
A. JB o ss EAP 6 ( all versio n s)
Add the system property:
org.jboss.as.logging.per-deployment=false
B. JB o ss EAP 6 .3 ( an d h ig h er)
Exclude the logging subsystem using a jbo ss-d epl o yment-structure. xml file. For
details on how to do this, see Exclude a Subsystem from a Deployment in the Development Guide.
Report a bug
12.5. Logging Profiles

12.5.1. About Logging Profiles
Important
Logging profiles are only available in version 6.1.0 and later. They cannot be configured
using the management console.
Logging profiles are independent sets of logging configuration that can be assigned to deployed
applications. As with the regular logging subsystem, a logging profile can define handlers,
categories and a root logger but cannot refer to configuration in other profiles or the main logging
subsystem. The design of logging profiles mimics the logging subsystem for ease of configuration.
The use of logging profiles allows administrators to create logging configuration that are specific to
one or more applications without affecting any other logging configuration. Because each profile is
defined in the server configuration, the logging configuration can be changed without requiring that
the affected applications be redeployed.
Each logging profile can have the following configuration:
278
A unique name. This is required.

Any number of log handlers.
Any number of log categories.
Up to one root logger.
An application can specify a logging profile to use in its MANIFEST . MF file, using the loggingprofile attribute.
Report a bug
12.5.2. Creat e a new Logging Profile using t he CLI

A new logging profile can be created using the CLI command below, replacing NAME with your
required profile name:
/subsystem=logging/logging-profile=NAME:add
This will create a new empty profile to which handlers, categories and a root logger can be added.
Report a bug
12.5.3. Configuring a Logging Profile using t he CLI

A logging profile can be configured with log handlers, categories and a root logger using almost
exactly the same syntax as when using the main logging subsystem.
There are only two differences between configuring the main logging subsystem and the logging
profile:
1. The root configuration path is /subsystem= l o g g i ng /l o g g i ng -pro fi l e= NAME
2. A logging profile cannot contain other logging profiles.
Refer to the appropriate logging management task:
Section 12.3.1, Configure the Root Logger with the CLI
Section 12.3.2, Configure a Log Category in the CLI
Section 12.3.3, Configure a Console Log Handler in the CLI
Section 12.3.4, Configure a File Log Handler in the CLI
Section 12.3.5, Configure a Periodic Log Handler in the CLI
Section 12.3.6, Configure a Size Log Handler in the CLI
Section 12.3.8, Configure a Async Log Handler in the CLI
Examp le 12.79 . C reat in g an d C o n f ig u rin g a Lo g g in g Pro f ile

Creating a logging profile and adding a category and file log handler.
1. Create the profile:
279
/subsystem=logging/logging-profile=accounts-app-profile:add
2. Create file handler
/subsystem=logging/logging-profile=accounts-app-profile/filehandler=ejb-trace-file:add(file={path=>"ejb-trace.log",
/subsystem=logging/logging-profile=accounts-app-profile/filehandler=ejb-trace-file:write-attribute(name="level",
value="DEBUG")
3. Create logger category
/subsystem=logging/logging-profile=accounts-appprofile/logger=com.company.accounts.ejbs:add(level=TRACE)
4. Assign file handler to category
/subsystem=logging/logging-profile=accounts-appprofile/logger=com.company.accounts.ejbs:add-handler(name="ejbtrace-file")
Report a bug
12.5.4 . Specify a Logging Profile in an Applicat ion

An application specifies the logging profile to use in its MANIFEST . MF file.
Prereq u isit es:
1. You must know the name of the logging profile that has been setup on the server for this
application to use. Ask your server administrator for the name of the profile to use.
Pro ced u re 12.9 . Ad d Lo g g in g Pro f ile co n f ig u rat io n t o an Ap p licat io n
Ed it MANIFEST . MF
If your application does not have a MANIFEST . MF file: create one with the following content,
replacing NAME with the required profile name.
Manifest-Version: 1.0
Logging-Profile: NAME
If your application already has a MANIFEST . MF file: add the following line to it, replacing NAME
with the required profile name.
Logging-Profile: NAME
280
Note
If you are using Maven and the maven-war-pl ug i n, you can put your MANIFEST.MF file in
src/mai n/reso urces/MET A-INF/ and add the following configuration to your po m. xml
file.
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<archive>
<manifestFile>src/main/resources/METAINF/MANIFEST.MF</manifestFile>
</archive>
</configuration>
</plugin>
When the application is deployed it will use the configuration in the specified logging profile for its
log messages.
Report a bug
12.5.5. Example Logging Profile Configurat ion

This example shows the configuration of a logging profile and the application that makes use of it.
The CLI session is shown, the XML configuration that is generated, and the MANIFEST . MF file of the
application.
The logging profile example has the following characteristics:
The Name is acco unts-app-pro fi l e.
The Log Category is co m. co mpany. acco unts. ejbs.
The Log level T R AC E.
The Log handler is a file handler using the file ejb-trace. l o g .
Examp le 12.80. C LI sessio n

localhost:bin user$ ./jboss-cli.sh -c
[standalone@ localhost:9999 /] /subsystem=logging/loggingprofile=accounts-app-profile:add
[standalone@ localhost:9999 /] /subsystem=logging/loggingprofile=accounts-app-profile/file-handler=ejb-trace-file:add(file=
{path=>"ejb-trace.log", "relative-to"=>"jboss.server.log.dir"})
[standalone@ localhost:9999 /] /subsystem=logging/loggingprofile=accounts-app-profile/file-handler=ejb-trace-file:writeattribute(name="level", value="DEBUG")
281

[standalone@ localhost:9999 /] /subsystem=logging/loggingprofile=accounts-appprofile/logger=com.company.accounts.ejbs:add(level=TRACE)
[standalone@ localhost:9999 /] /subsystem=logging/loggingprofile=accounts-app-profile/logger=com.company.accounts.ejbs:addhandler(name="ejb-trace-file")
Examp le 12.81. XML C o n f ig u rat io n

<logging-profiles>
<logging-profile name="accounts-app-profile">
<file-handler name="ejb-trace-file">
<level name="DEBUG"/>
<file relative-to="jboss.server.log.dir" path="ejbtrace.log"/>
</file-handler>
<logger category="com.company.accounts.ejbs">
<level name="TRACE"/>
<handlers>
<handler name="ejb-trace-file"/>
</handlers>
</logger>
</logging-profile>
</logging-profiles>
Examp le 12.82. Ap p licat io n MAN IFEST .MF f ile

Manifest-Version: 1.0
Logging-Profile: accounts-app-profile
Report a bug
12.6. Logging Configurat ion Propert ies

12.6.1. Root Logger Propert ies
T ab le 12.6 . R o o t Lo g g er Pro p ert ies
Pro p ert y
D at at yp e
D escrip t io n
level
String
handlers
String[]
The maximum level of log message that the root logger

records.
A list of log handlers that are used by the root logger.
282
Pro p ert y
D at at yp e
D escrip t io n
filter-spec
String
An expression value that defines a filter. The following

expression defines a filter that excludes log entries that do
not match a pattern: no t(match("JBAS. *"))
Note
A fi l ter-spec specified for the root logger is not inherited by other handlers. Instead a
fi l ter-spec must be specified per handler.
Report a bug
12.6.2. Log Cat egory Propert ies

T ab le 12.7. Lo g C at eg o ry Pro p ert ies
Pro p ert y
D at at yp e
D escrip t io n
level
String
handlers
use-parenthandlers
category
String[]
Boolean
filter-spec
String
The maximum level of log message that the log category

records.
A list of log handlers associated with the logger.
If set to true, this category will use the log handlers of the
root logger in addition to any other assigned handlers.
The log category from which log messages will be
captured.
expression defines a filter that does not match a pattern:
no t(match("JBAS. *"))
String
Report a bug
12.6.3. Console Log Handler Propert ies

T ab le 12.8. C o n so le Lo g H an d ler Pro p ert ies
Pro p ert y
D at at yp e
D escrip t io n
level
String
encoding
formatter
named-formatter
String
String
String
target
String
autoflush
Boolean
name
enabled
String
Boolean
The maximum level of log message the log handler

records.
The character encoding scheme to be used for the output.
The log formatter used by this log handler.
The name of the defined formatter to be used on the
handler.
The system output stream where the output of the log
handler goes. This can be System.err or System.out for the
system error stream or standard out stream respectively.
If set to true the log messages will be sent to the handlers
target immediately upon receipt.
The unique identifier for this log handler.
If set to true, the handler is enabled and functioning as
normal. If set to fal se, the handler is ignored when
processing log messages.
283
Pro p ert y
D at at yp e
D escrip t io n
filter-spec
String

Report a bug
12.6.4 . File Log Handler Propert ies

T ab le 12.9 . File Lo g H an d ler Pro p ert ies
Pro p ert y
D at at yp e
D escrip t io n
level
String
encoding
formatter
named-formatter
String
String
String
append
Boolean
autoflush
Boolean
name
file
String
Object
relative-to
String
path
String
enabled
Boolean
filter-spec
String

records.
handler.
If set to true then all messages written by this handler will
be appended to the file if it already exists. If set to false a
new file will be created each time the application server
launches. Changes to append require a server reboot to
take effect.
assigned file immediately upon receipt.
The object that represents the file where the output of this
log handler is written to. It has two configuration
properties, rel ati ve-to and path.
This is a property of the file object and is the directory
where the log file is written to. JBoss EAP 6 file path
variables can be specified here. The
jbo ss. server. l o g . d i r variable points to the l o g /
directory of the server.
This is a property of the file object and is the name of the
file where the log messages will be written. It is a relative
path name that is appended to the value of the
rel ati ve-to property to determine the complete path.
Report a bug
12.6.5. Periodic Log Handler Propert ies

T ab le 12.10. Perio d ic Lo g H an d ler Pro p ert ies
284
Pro p ert y
D at at yp e
D escrip t io n
append
Boolean
autoflush
Boolean
encoding
formatter
named-formatter
String
String
String
level
String
name
file
String
Object
relative-to
String
path
String
suffix
String

be appended to the file if it already exists. If set to fal se a
take effect.
handler.
records.
Object that represents the file to which the output of this
log handler is written. It has two configuration properties,
rel ati ve-to and path.
containing the log file. File path variables can be specified
here. The jbo ss. server. l o g . d i r variable points to
the l o g / directory of the server.
This String is appended to the filename of the rotated logs
and is used to determine the frequency of rotation. The
format of the suffix is a dot (.) followed by a d ate Stri ng
which is able to be parsed by the Si mpl eD ateFo rmat
class. The log is rotated on the basis of the smallest time
unit defined by the suffix. Note that the smallest time unit
allowed in the suffi x attribute is minutes.
For example, a suffi x value of . Y Y Y Y -MM-d d will result
in daily log rotation. Assuming a log file named
server. l o g and a suffi x value of . Y Y Y Y -MM-d d , the
log file rotated on 20 October 2014 would be named
server. l o g . 20 14 -10 -19 . For a periodic log handler,
the suffix includes the previous value for the smallest time
unit. In this example the value for d d is 19 , the previous
day.
enabled
Boolean
filter-spec
String

no t(match("JBAS. *")).
Report a bug
12.6.6. Siz e Log Handler Propert ies
285
T ab le 12.11. Siz e Lo g H an d ler Pro p ert ies

Pro p ert y
D at at yp e
D escrip t io n
append
Boolean
autoflush
Boolean
encoding
formatter
named-formatter
String
String
String
level
String
name
file
String
Object
relative-to
String
path
String
rotate-size
Integer
max-backupindex
Integer

take effect.
handler.
records.
Object that represents the file where the output of this log
handler is written to. It has two configuration properties,
The maximum size that the log file can reach before it is
rotated. A single character appended to the number
indicates the size units: b for bytes, k for kilobytes, m for
megabytes, g for gigabytes. Eg. 50 m for 50 megabytes.
The maximum number of rotated logs that are kept. When
this number is reached, the oldest log is reused. D efault: 1.
Available from JBoss EAP 6.4. If the suffi x attribute is
used, the suffix of rotated log files is included in the
rotation algorithm. When the log file is rotated, the oldest
file whose name starts with name+suffi x is deleted, the
remaining rotated log files have their numeric suffix
incremented and the newly rotated log file is given the
numeric suffix 1.
Assume a log file name server. l o g , a suffi x value of
. Y Y Y Y -mm, and max-backup-i nd ex value of 3. When
the log file has been rotated twice, log file names could be
server. l o g , server. l o g . 20 14 -10 . 1 and
server. l o g . 20 14 -10 . 2. The next time the log file is
rotated, server. l o g . 20 14 -10 . 2 is deleted,
server. l o g . 20 14 -10 . 1 is renamed
server. l o g . 20 14 -10 . 2 and the newly rotated log file
is named server. l o g . 20 14 -10 . 1.
286
Pro p ert y
D at at yp e
D escrip t io n
enabled
Boolean
filter-spec
String
rotate-on-boot
Boolean
suffix
String

If set to true, a new log file will be created on server
restart. D efault is fal se.
Available from JBoss EAP 6.4. This String is included in
the suffix appended to rotated logs. The format of the
suffix is a dot (.) followed by a date String which is able
to be parsed by the Si mpl eD ateFo rmat class.
For example, assuming a log file named server. l o g
and a suffi x value of . Y Y Y Y -mm, the first log file rotated
on 1 October 2014 would be named server. l o g . 20 14 10 . 1. In this example, the 20 14 -10 portion of the suffix is
derived from the value of suffix.
Report a bug
12.6.7. Periodic Siz e Rot at ing Log Handler Propert ies

T ab le 12.12. Perio d ic Siz e Lo g H an d ler Pro p ert ies
Pro p ert y
D at at yp e
D escrip t io n
append
Boolean
rotate-size
String
max-backupindex
Integer

take effect.
The maximum size that the log file can reach before it is
rotated.
The maximum number of size-rotated logs that are kept.
When this number is reached, the oldest log is reused.
D efault: 1.
This setting only applies to logs that are rotated based on
file size.
Note that if a file is rotated with a date format suffix, it will
not be purged using the max-backup-i nd ex option.
287
Pro p ert y
D at at yp e
D escrip t io n
suffix
String
This String is appended to the filename of the rotated logs

and is used to determine the frequency of rotation. The
format of the suffix is a dot (.) followed by a d ate Stri ng
which is able to be parsed by the Si mpl eD ateFo rmat
class. The log is rotated on the basis of the smallest time
unit defined by the suffix. Note that the smallest time unit
allowed in the suffi x attribute is minutes.
For example, a suffi x value of . Y Y Y Y -MM-d d will result
in daily log rotation. Assuming a log file named
server. l o g and a suffi x value of . Y Y Y Y -MM-d d , the
log file rotated on 20 October 2014 would be named
server. l o g . 20 14 -10 -19 . For a periodic log handler,
the suffix includes the previous value for the smallest time
unit. In this example the value for d d is 19 , the previous
day.
autoflush
Boolean
file
Object
relative-to
String
path
String
enabled
Boolean
filter-spec
String
rotate-on-boot
Boolean
formatter
level
String
String
name
named-formatter
String
String
encoding
String

Object that represents the file where the output of this log
handler is written to. It has two configuration properties,
If set to true, a new log file will be created on server
restart. D efault is fal se.
The minimum level of log message the log handler
records.
handler.
Report a bug
12.6.8. Async Log Handler Propert ies

T ab le 12.13. Asyn c Lo g H an d ler Pro p ert ies
288
Pro p ert y
D at at yp e
D escrip t io n
level
String
name
encoding
formatter
queue-length
String
String
String
Integer
overflow-action
String
subhandlers
String[]
enabled
Boolean
filter-spec
String

records.
Maximum number of log messages that will be held by this
handler while waiting for sub-handlers to respond.
How this handler responds when its queue length is
exceeded. This can be set to BLO C K or D ISC AR D . BLO C K
makes the logging application wait until there is available
space in the queue. This is the same behavior as an nonasync log handler. D ISC AR D allows the logging
application to continue but the log message is deleted.
This is the list of log handlers to which this async handler
passes its log messages.
Report a bug
12.7. Sample XML Configurat ion for Logging

12.7.1. Sample XML Configurat ion for t he Root Logger
<root-logger>
<level name="INFO"/>
<handlers>
<handler name="CONSOLE"/>
<handler name="FILE"/>
</handlers>
</root-logger>
Report a bug
12.7.2. Sample XML Configurat ion for a Log Cat egory

<logger category="com.company.accounts.rec">
<handlers>
<handler name="accounts-rec"/>
</handlers>
</logger>
Report a bug
12.7.3. Sample XML Configurat ion for a Console Log Handler
289
<console-handler name="CONSOLE">
<formatter>
<pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
</formatter>
</console-handler>
Report a bug
12.7.4 . Sample XML Configurat ion for a File Log Handler

<file-handler name="accounts-rec-trail" autoflush="true">
<file relative-to="jboss.server.log.dir" path="accounts-rectrail.log"/>
<append value="true"/>
</file-handler>
Report a bug
12.7.5. Sample XML Configurat ion for a Periodic Log Handler

<periodic-rotating-file-handler name="FILE">
<formatter>
<pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t)
%s%E%n"/>
</formatter>
<file relative-to="jboss.server.log.dir" path="server.log"/>
<suffix value=".yyyy-MM-dd"/>
</periodic-rotating-file-handler>
Report a bug
12.7.6. Sample XML Configurat ion for a Siz e Log Handler

<size-rotating-file-handler name="accounts_debug" autoflush="false">
<level name="DEBUG"/>
<file relative-to="jboss.server.log.dir" path="accounts-debug.log"/>
<rotate-size value="500k"/>
<max-backup-index value="5"/>
</size-rotating-file-handler>
Report a bug
12.7.7. Sample XML Configurat ion for a Periodic Siz e Rot at ing Log Handler
<periodic-size-rotating-file-handler
name="Periodic_size_rotating_Handler" autoflush="false">
<file relative-to="jboss.server.log.dir" path="Sample.log"/>
290
<max-backup-index value="1"/>
<suffix value=".yyyy.MM.dd"/>
<append value="false"/>
<periodic-size-rotating-file-handler>
Report a bug
12.7.8. Sample XML Configurat ion for a Async Log Handler

<async-handler name="Async_NFS_handlers">
<queue-length value="512"/>
<overflow-action value="block"/>
<subhandlers>
<handler name="FILE"/>
<handler name="accounts-record"/>
</subhandlers>
</async-handler>
Report a bug
291
Chapter 13. Infinispan

13.1. About Infinispan
Infinispan is a Java data grid platform. It provides a JSR-107 compatible cache interface for
managing cached data.
The following Infinispan cache containers are used in JBoss Enterprise Application Platform 6:
web for Web Session Clustering
ejb for Stateful Session Bean Clustering
hi bernate for entity caching
si ng l eto n for singleton caching
Each cache container defines a " repl" and a " dist" cache. These caches should not be used directly
by user applications.
Important
Users can add more cache containers and caches, and reference them via JND I. However, this
is unsupported in JBoss Enterprise Application Platform 6.
For more information about Infinispan functionality and configuration options see the Infinispan
Documentation.
Report a bug
13.2. Clust ering modes

Clustering can be configured in two different ways in JBoss EAP 6 using Infinispan. The correct
method for your application will depend on your requirements. There is a trade off between
availability, consistency, reliability and scalability with each mode. Before choosing a clustering
mode, you must identify what are the most important features of your network for you, and balance
those requirements.
R ep licat ed Mo d e
Replicated Mode automatically detects and adds new instances on the cluster. Changes made to
these instances will be replicated to all nodes on the cluster. Replicated mode typically works best in
small clusters because of the amount of information that has to be replicated over the network.
Infinispan can be configured to use UD P multicast, which alleviates network traffic congestion to a
degree.
D ist rib u t io n Mo d e
D istribution mode allows Infinispan to scale the cluster linearly. D istribution mode uses a consistent
hash algorithm to determine where in a cluster a new node should be placed. The number of copies
of information to be kept is configurable. There is a trade off between the number of copies kept,
durability of the data and performance: the more copies that are kept, the more impact on
292
Chapt er 1 3. Infinispan
performance, but the less likely you are to lose data in a server failure. The hash algorithm also
works to reduce network traffic by locating entries without multicasting or storing metadata.
One should consider using D istribution (dist) mode as a caching strategy when the cluster size
exceeds 6-8 nodes. With D istribution mode, data is distributed to only a subset of nodes within the
cluster, as opposed to all nodes (default Replicated mode).
Syn ch ro n o u s an d Asyn ch ro n o u s R ep licat io n
Replication can be performed either in synchronous or asynchronous mode, and the mode chosen
depends on your requirements and your application. With synchronous replication, the thread that
handles the user request is blocked until replication has been successful. Only when the replication
is successful, a response is sent back to the client and the thread is released. Synchronous
replication has an impact on network traffic because it requires a response from each node in the
cluster. It has the advantage, however, of ensuring that all modifications have been made to all
nodes in the cluster.
Asynchronous replication is carried out in the background. Infinispan implements a replication
queue, which is used by a background thread to carry out replication. Replication is triggered either
on a time basis, or on the queue size. A replication queue allows increased performance because
there is no conversation being carried out between the cluster nodes. The trade off with
asynchronous replication is that it is not quite so accurate. Failed replication attempts are written to a
log, not notified in real time.
Report a bug
13.3. Cache Cont ainers

C ach e C o n t ain ers
A cache container is repository for the caches used by a subsystem. For Infinispan default
cache containers are defined in the configuration xml files (standalone-ha.xml, standalonefull-ha.xml, domain.xml). One cache is defined as the default cache, which is the cache that
will be used for clustering.
Examp le 13.1. C ach e co n t ain er d ef in it io n s f ro m st an d alo n e- h a.xml

co n f ig u rat io n f ile
<subsystem xmlns="urn:jboss:domain:infinispan:1.5">
<cache-container name="singleton" aliases="cluster hapartition" default-cache="default">
<transport lock-timeout="60000"/>
<replicated-cache name="default" mode="SYNC"
batching="true">
<locking isolation="REPEATABLE_READ"/>
</replicated-cache>
</cache-container>
<cache-container name="web" aliases="standard-sessioncache" default-cache="repl"
module="org.jboss.as.clustering.web.infinispan">
<replicated-cache name="repl" mode="ASYNC"
batching="true">
<file-store/>
</replicated-cache>
293
<replicated-cache name="sso" mode="SYNC"

batching="true"/>
<distributed-cache name="dist" l1-lifespan="0"
mode="ASYNC" batching="true">
<file-store/>
</distributed-cache>
</cache-container>
Note the default cache defined in each cache container. In this example, in the web cache
container, the repl cache is defined as the default. The repl cache will therefore be used
when clustering web sessions.
The cache containers and cache attributes can be configured using the Management
Console or CLI commands, but it is not advisable to change the names of either cache
containers or caches.
C o n f ig u re C ach e C o n t ain ers
Cache containers for Infinispan can be configured using the CLI or the Management
Console.
Pro ced u re 13.1. C o n f ig u re t h e In f in isp an C ach e C o n t ain ers in t h e Man ag emen t
C o n so le
1. Select the C o n f ig u rat io n tab from the top of the screen.
2. For D omain mode only, select either h a or f u ll- h a from the drop down menu at top
left.
3. Expand the Su b syst ems menu, then expand the In f in isp an menu. Select C ach e
C o n t ain ers.
4. Select a cache container from the C ache C o ntai ners table.
5. Ad d , R emo ve o r Set D ef au lt C ach e C o n t ain er
a. To create a new cache container, click Ad d from the C ache C o ntai ners
table.
b. To remove a cache container, select the cache container in the C ache
C o ntai ners table. Click R emo ve and click O K to confirm.
c. To set a cache container as default, click Set D efaul t, enter a cache
container name from the drop down list, click Save to confirm.
6. To add or update the attributes of a cache container, select the cache container in
the C ache C o ntai ners table. Select one from the At t rib u t es, T ran sp o rt and
Aliases tabs in the D etai l s area of the screen, and click Ed i t. For help about
the content of the At t rib u t es, T ran sp o rt and Aliases tabs, click Need Hel p?.
Pro ced u re 13.2. C o n f ig u re t h e In f in isp an C ach e C o n t ain ers in t h e Man ag emen t
C LI
1. To get a list of configurable attributes, enter the following CLI command:
/profile=profile name/subsystem=infinispan/cachecontainer=container name:read-resource
294
2. You can use the Management CLI to add, remove and update cache containers.
Before issuing any commands to do with cache containers, ensure that you use the
correct profile in the Management CLI command.
a. Ad d a C ach e C o n t ain er
To add a cache container base your command on the following example:
/profile=profile-name/subsystem=infinispan/cachecontainer="cache container name":add
b. R emo ve a C ach e C o n t ain er
To remove a cache container base your command on the following example:
/profile=profile-name/subsystem=infinispan/cachecontainer="cache container name":remove
c. U p d at e C ach e C o n t ain er at t rib u t es
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
statistics-enabled to true.
/profile=profile name/subsystem=infinispan/cachecontainer=cache container name:writeattribute(name=statistics-enabled,value=true)
Report a bug
13.4 . About Infinispan St at ist ics

Runtime statistics about Infinispan cache and cache-container objects can be enabled for
monitoring purposes. Statistics collection is not enabled by default for performance reasons.
Warning
Enabling Infinispan statistics can have a negative impact on the performance of the Infinispan
subsystem. Statistics should be enabled only when required.
Statistics collection can be enabled for each cache-container, cache or both. The statistics option for
each cache overrides the option for the cache-container. Enabling or disabling statistics collection
for a cache container will cause all caches in that container to inherit the setting, unless they
explicitly specify their own. If only a cache-container is enabled for statistics, useful statistics are
available.
Report a bug
13.5. Swit ching t o Dist ribut ed Cache Mode for Web Session
Replicat ion
295
Change the web cache-container for Infinispan subsystem to d i st from repl . The o wners attribute
defines the number of cluster nodes that will hold the session data. One of them is called primary
owner, and the others are backup owners.
Following is the CLI command to update the cache mode to d i st with three owners assuming an ha
profile is being used:
/subsystem=infinispan/cache-container=web/:write-attribute(name=defaultcache,value=dist)
/subsystem=infinispan/cache-container=web/distributed-cache=dist/:writeattribute(name=owners,value=3)
Running the above CLI will yield the following output:
<cache-container name="web" aliases="standard-session-cache" defaultcache="dist" module="org.jboss.as.clustering.web.infinispan">
...
<distributed-cache name="dist" owners="3" l1-lifespan="0" mode="ASYNC"
batching="true">
<file-store/>
</distributed-cache>
</cache-container>
Report a bug
13.6. Enable Infinispan St at ist ics Collect ion

Statistics collection can be enabled from either the startup configuration file (for example
stand al o ne. xml , stand al o ne-ha. xml , d o mai n. xml ) or the Management CLI.
Report a bug
13.6.1. Enable Infinispan St at ist ics Collect ion in t he St art up Configurat ion
File
Pro ced u re 13.3. En ab le In f in isp an St at ist ics in t h e St art u p C o n f ig u rat io n File
Add the attribute stati sti cs-enabl ed =VALUE to the required cache-co ntai ner or cache
XML tag under the Infinispan subsystem.
Examp le 13.2. En ab le St at ist ics C o llect io n f o r a cache
<replicated-cache name="sso" mode="SYNC" batching="true" statisticsenabled="true"/>
Examp le 13.3. En ab le St at ist ics C o llect io n f o r a cache-co ntai ner
296
<cache-container name="singleton" aliases="cluster ha-partition"

default-cache="default" statistics-enabled="true">
Report a bug
13.6.2. Enable Infinispan St at ist ics Collect ion from t he Management CLI
Pro ced u re 13.4 . En ab le In f in isp an St at ist ics C o llect io n f ro m t h e Man ag emen t C LI
In this procedure:
CACHE_CONTAINER is the preferred cache-co ntai ner (for example, web)
CACHE_TYPE is the preferred cache type (for example, d i stri buted -cache)
CACHE is the cache name (for example, d i st)
1. Enter the following command:
/subsystem=infinispan/cachecontainer=CACHE_CONTAINER/CACHE_TYPE=CACHE:writeattribute(name=statistics-enabled,value=true)
2. Enter the following command to reload the server:
reload
Note
To undefine an attribute, enter the following command:
/subsystem=infinispan/cachecontainer=CACHE_CONTAINER/CACHE_TYPE=CACHE:undefineattribute(name=statistics-enabled)
Report a bug
13.6.3. Verify Infinispan St at ist ics Collect ion is Enabled

Pro ced u re 13.5. Verif y In f in isp an St at ist ics C o llect io n is En ab led
D epending on whether you are confirming that statistics collection is enabled on a cache or cacheco ntai ner, use one of the following Management CLI commands.
A. Fo r a cache
/subsystem= i nfi ni span/cacheco ntai ner= CACHE_CONTAINER/CACHE_TYPE= CACHE: read attri bute(name= stati sti cs-enabl ed )
297
B. Fo r a cache-co ntai ner

/subsystem= i nfi ni span/cache-co ntai ner= CACHE_CONTAINER: read attri bute(name= stati sti cs-enabl ed )
Report a bug
13.7. JGroups
13.7.1. About JGroups
JGroups is a messaging toolkit which allows developers to create reliable messaging applications
where system reliability is an issue. JGroups can be used to create clusters whose nodes can send
messages to each other.
The JGroups subsystem provides all the communication mechanisms for how the servers in a cluster
talk to each other. EAP is preconfigured with two JGroups stacks.
udp - the nodes in the cluster use UD P (User D atagram Protocol) multicasting to communicate
with each other. UD P is generally faster but less reliable than TCP.
tcp - the nodes in the cluster use TCP (Transmission Control Protocol) to communicate with each
other. TCP tends to be slower than UD P, but will more reliably deliver data to its destination.
The preconfigured stacks can be used, or you can define your own to suit your system's specific
requirements.
Report a bug
13.8. JGroups T roubleshoot ing

13.8.1. Nodes do not form a clust er
Make sure your machine is set up correctly for IP multicast. There are 2 test programs that can be
used to detect this: McastReceiverTest and McastSenderTest. For example:
java -cp EAP_HOME/bi n/cl i ent/jbo ss-cl i ent. jar
o rg . jg ro ups. tests. McastR ecei verT est -mcast_ad d r 230 . 11. 11. 11 -po rt 5555
-bi nd _ad d r YOUR_BIND_ADDRESS
Then in another window start McastSend erT est:
java -cp EAP_HOME/bi n/cl i ent/jbo ss-cl i ent. jar
o rg . jg ro ups. tests. McastSend erT est -mcast_ad d r 230 . 11. 11. 11 -po rt 5555 bi nd _ad d r YOUR_BIND_ADDRESS
If you want to bind to a specific network interface card (NIC), use -bi nd _ad d r 192.168.0.2, where
192.168.0.2 is the IP address of the NIC to which you want to bind. Use this parameter in both the
sender and the receiver.
You should be able to type in the McastSend erT est window and see the output in the
McastR ecei verT est window. If not, try to use -ttl 32 in the sender. If this still fails, consult a
298
system administrator to help you setup IP multicast correctly, and ask the admin to make sure that
multicast will work on the interface you have chosen or, if the machines have multiple interfaces, ask
to be told the correct interface. Once you know multicast is working properly on each machine in your
cluster, you can repeat the above test to test the network, putting the sender on one machine and the
receiver on another.
Report a bug
13.8.2. Causes of missing heart beat s in FD

Sometimes a member is suspected by FD because a heartbeat ack has not been received for some
time T (defined by timeout and max_tries). This can have multiple reasons, e.g. in a cluster of
A,B,C,D ; C can be suspected if (note that A pings B, B pings C, C pings D and D pings A):
B or C are running at 100% CPU for more than T seconds. So even if C sends a heartbeat ack to
B, B may not be able to process it because it is at 100%
B or C are garbage collecting, same as above.
A combination of the 2 cases above
The network loses packets. This usually happens when there is a lot of traffic on the network, and
the switch starts dropping packets (usually broadcasts first, then IP multicasts, TCP packets last).
B or C are processing a callback. Let us say C received a remote method call over its channel and
takes T+1 seconds to process it. D uring this time, C will not process any other messages,
including heartbeats, and therefore B will not receive the heartbeat ack and will suspect C.
Report a bug
299
Chapter 14. JVM

14 .1. About JVM
14 .1.1. About JVM Set t ings
Configuration of Java Virtual Machine (JVM) settings varies between the managed domain and
standalone server instances. In a managed domain, the JVM settings are declared in ho st. xml and
d o mai n. xml configuration files, and determined by the domain controller components responsible
for starting and stopping server processes. In a standalone server instance, the server startup
processes can pass command line settings at startup. These can be declared from the command line
or via the System P ro perti es screen in the Management Console.
Note
System properties not configured in JAVA_OPTS cannot be used for properties used by JBoss
Modules at boot time, nor can it be used for other JVM properties such as
java. uti l . l o g g i ng . manag er.
Man ag ed D o main
An important feature of the managed domain is the ability to define JVM settings at multiple levels.
You can configure custom JVM settings at the host level, by server group, or by server instance. The
more specialized child elements will override the parent configuration, allowing for the declaration of
specific server configurations without requiring exclusions at the group or host level. This also
allows the parent configuration to be inherited by the other levels until settings are either declared in
the configuration files or passed at runtime.
Examp le 14 .1. JVM set t in g s in t h e d o main co n f ig u rat io n f ile

The following example shows a JVM declaration for a server group in the d o mai n. xml
configuration file.
<server-groups>
<server-group name="main-server-group" profile="default">
<jvm name="default">
<heap size="64m" max-size="512m"/>
</jvm>
</server-group>
<server-group name="other-server-group" profile="default">
</jvm>
</server-group>
</server-groups>
300
Chapt er 1 4 . JVM
In this instance a server group called mai n-server-g ro up is declaring a heap size of 64
megabytes, and a maximum heap size of 512 megabytes. Any server that belongs to this group will
inherit these settings. You can change these settings for the group as a whole, by the host, or the
individual server.
Examp le 14 .2. D o main set t in g s in t h e h o st co n f ig u rat io n f ile

The following example shows a JVM declaration for a server group in the ho st. xml configuration
file.
<servers>
<server name="server-one" group="main-server-group" autostart="true">
<jvm name="default"/>
</server>
<server name="server-two" group="main-server-group" autostart="true">
</jvm>
<socket-bindings port-offset="150"/>
</server>
<server name="server-three" group="other-server-group" autostart="false">
<socket-bindings port-offset="250"/>
</server>
</servers>
In this instance, a server named server-two belongs to the server group named mai n-serverg ro up, inheriting the JVM settings from the d efaul t JVM group. In the previous example, the
main heap size for mai n-server-g ro up was set at 512 megabytes. By declaring the lower
maximum heap size of 256 megabytes, server-two can override the d o mai n. xml settings to
fine-tune performance as desired.
St an d alo n e server set t in g s at ru n t ime

The JVM settings for standalone server instances can be declared at runtime by setting the
JAVA_O P T S environment variable before starting the server. An example of setting the JAVA_O P T S
environment variable at the Linux command-line is:
[user@ host bin]$ export JAVA_OPTS="-Xmx1024M"
The same setting can be used in a Microsoft Windows environment, as follows:
C:\> set JAVA_OPTS="Xmx1024M"
Alternatively, JVM settings can be added to the stand al o ne. co nf file found in the EAP_HOME/bi n
folder, which contains examples of options to pass to the JVM.
301
Warning
Setting the JAVA_OPTS environment variable will re-define the default values for the
JAVA_OPTS environment variable. This can break or terminate the start of JBoss EAP.
Report a bug
14 .1.2. Display t he JVM St at us in t he Management Console

Prereq u isit es
Section 2.2.2, Start JBoss EAP 6 as a Standalone Server
Java Virtual Machine (JVM) status can be displayed in the Management Console for either the
standalone server or a managed domain. The console shows the heap usage, non heap usage, and
thread usage of the server. While the statistics are not displayed in real-time, you can refresh the
console display to provide an up-to-date overview of JVM resources.
The JVM status shows the following values.
T ab le 14 .1. JVM St at u s At t rib u t es
T yp e
D escrip t io n
Max
The maximum amount of memory that can be used for memory

management. The maximum availabe memory is shown by the light grey
bar.
The amount of used memory. The amount of used memory is shown by
the dark grey bar.
The amount of memory that is committed for the Java virtual machine to
use. The committed memory is shown by the dark grey bar.
Used
Committed
Pro ced u re 14 .1. D isp lay t h e JVM St at u s in t h e Man ag emen t C o n so le

1. A. D isp lay t h e JVM st at u s f o r a st an d alo n e server in st an ce
Select the R u n t ime tab from the top of the screen. Expand the St at u s menu, then expand
the Plat f o rm menu. Select JVM.
B. D isp lay t h e JVM st at u s f o r a man ag ed d o main
Select the R u n t ime tab from the top of the screen. Expand the Server St at u s menu, then
expand the Plat f o rm menu. Select JVM.
2. The managed domain can provide visibility of all server instances in the server group, but will
only allow you to view one server at a time by selecting from the server menu. To view the
status of other servers in your server group, click C hang e Server left of the screen to select
from the host and servers displayed in your group. Select the required server or host and the
JVM details will change. Click C l o se to finish.
R esu lt
302
Chapt er 1 4 . JVM
The status of the JVM settings for the server instance are displayed.
Report a bug
14 .1.3. Configuring JVM

The <jvm></jvm> tags support the usage of <jvm-options></jvm-options>, which can be used to add
parameters to the JVM configuration using the <option value=" VALUE" /> tag.
Examp le 14 .3. U se o f <jvm- o p t io n s>

<permgen max-size="256m"/>
<jvm-options>
<option value="-XX:+UseCompressedOops"/>
</jvm-options>
</jvm>
C o n f ig u rin g JVM U sin g C LI

To configure JVM using CLI, use the following syntax:
# cd /server-group=main-server-group/jvm=default
# :add-jvm-option(jvm-option="-XX:+UseCompressedOops")
{
"server-groups" => {"main-server-group" => {"host" => {"master" => {
"server-one" => {"response" => {
"operation-requires-restart" => true,
"process-state" => "restart-required"
}
}},
"server-two" => {"response" => {
}
}}
}}}}
}
# :read-resource
# Expected Result:
[domain@ localhost:9999 jvm=default] :read-resource
{
303

"result" => {
"agent-lib" => undefined,
"agent-path" => undefined,
"env-classpath-ignored" => undefined,
"environment-variables" => undefined,
"heap-size" => "1303m",
"java-agent" => undefined,
"java-home" => undefined,
"jvm-options" => ["-XX:+UseCompressedOops"],
"max-heap-size" => "1303m",
"max-permgen-size" => "256m",
"permgen-size" => undefined,
"stack-size" => undefined,
"type" => undefined
}
}
R emo vin g jvm- o p t io n s En t ry
To remove jvm-options entry, use the following syntax:
# cd /server-group=main-server-group/jvm=default
# :remove-jvm-option(jvm-option="-XX:+UseCompressedOops")
# Expected Result:
[domain@ localhost:9999 jvm=default] :remove-jvm-option(jvm-option="XX:+UseCompressedOops")
{
"server-groups" => {"main-server-group" => {"host" => {"master" => {
"server-one" => {"response" => {
}
}},
"server-two" => {"response" => {
}
}}
}}}}
}
Sp ecif yin g 32- B it o r 6 4 - B it Arch it ect u re
304
Chapt er 1 4 . JVM
In some environments, such as Hewlett-Packard HP-UX and Solaris, the -d 32 or -d 6 4 switch is

used to specify whether to run in a 32-bit or 64-bit JVM respectively. The default is 32-bit if neither
option is indicated.
Pro ced u re 14 .2. Sp ecif yin g 6 4 - B it Arch it ect u re f o r a St an d alo n e Server
1. Open the EAP_HOME/bi n/stand al o ne. co nf file.
2. Add the following line to append the -d 6 4 option to JAVA_O P T S.
JAVA_OPTS="$JAVA_OPTS -d64"
Pro ced u re 14 .3. Sp ecif yin g 6 4 - B it Arch it ect u re f o r a Man ag ed D o main
When running in a managed domain, you can specify the 64-bit environment for host and process
controllers in addition to server instances.
1. Set the host and process controllers to run in the 64-bit JVM.
a. Open the EAP_HOME/bi n/d o mai n. co nf file.
b. Add the following line to append the -d 6 4 option to JAVA_O P T S. Ensure that this is
inserted before P R O C ESS_C O NT R O LLER _JAVA_O P T S and
HO ST _C O NT R O LLER _JAVA_O P T S are set.
Examp le 14 .4 . JVM o p t io n s in d o mai n. co nf

#
#
JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m Djava.net.preferIPv4Stack=true"
JAVA_OPTS="$JAVA_OPTS Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS Djava.awt.headless=true"
JAVA_OPTS="$JAVA_OPTS -Djboss.modules.policypermissions=true"
else
echo "JAVA_OPTS already set in environment; overriding
default settings with values: $JAVA_OPTS"
fi
2. Set the server instances to run in the 64-bit JVM.

a. Add -d 6 4 as a JVM option in the appropriate host.xml configuration files.
Examp le 14 .5. JVM o p t io n s in ho st. xml
<jvms>
305
<permgen size="256m" max-size="256m"/>
<jvm-options>
<option value="-server"/>
<option value="-d64"/>
</jvm-options>
</jvm>
</jvms>
Note
The -d 6 4 option can be added for the appropriate hosts using the
Management CLI with the following command:
/host=HOST_NAME/jvm=default:add-jvm-option(jvm-option="d64")
Report a bug
14 .1.4 . About t he Java Securit y Manager

The Java Security Manager is a class that manages the external boundary of the Java Virtual
Machine (JVM) sandbox, controlling how code executing within the JVM can interact with resources
outside the JVM. When the Java Security Manager is activated, the Java API checks with the security
manager for approval before executing a wide range of potentially unsafe operations. The Java
Security Manager uses a security policy to determine whether a given action will be allowed or
denied.
Report a bug
14 .1.5. About Java Securit y Policies

A Java Security policy is a set of defined permissions for different classes of code. The Java Security
Manager compares actions requested by applications against the security policy. If an action is
allowed by the policy, the Security Manager will permit that action to take place. If the action is not
allowed by the policy, the Security Manager will deny that action. The security policy can define
permissions based on the location of code, on the code's signature, or based on the subject's
principals.
Security policy grant entries consist of the following configuration elements:
C o d eB ase
The URL location (excluding the host and domain information) where the code originates
from. This parameter is optional.
Sig n ed B y
The alias used in the keystore to reference the signer whose private key was used to sign
the code. This can be a single value or a comma-separated list of values. This parameter is
optional. If omitted, presence or lack of a signature has no impact on the Java Security
Manager.
306
Chapt er 1 4 . JVM
Manager.
Prin cip als
A list of principal_type/principal_name pairs, which must be present within the
executing thread's principal set. The Principals entry is optional. If it is omitted, it signifies
that the principals of the executing thread will have no impact on the Java Security
Manager.
Permissio n s
A permission is the access which is granted to the code. Many permissions are provided as
part of the Java Enterprise Edition 6 (Java EE 6) specification.
Report a bug
14 .1.6. Writ e a Java Securit y Policy

An application called po l i cyto o l is included with most JD K and JRE distributions, for the purpose
of creating and editing Java security policies. D etailed information about po l i cyto o l is linked
from http://docs.oracle.com/javase/6/docs/technotes/tools/. Alternatively, you can also write a security
policy using a text editor.
Pro ced u re 14 .4 . Set u p a n ew Java Secu rit y Man ag er Po licy
1. St art po l i cyto o l .
Start the po l i cyto o l tool in one of the following ways.
From your GUI or a command prompt, run /usr/bi n/po l i cyto o l .
Run po l i cyto o l . exe from your Start menu or from the bi n\ of your Java installation.
The location can vary.
2. C reat e a p o licy.
To create a policy, select Ad d P o l i cy Entry. Add the parameters you need, then click
D o ne.
Note
Use VFS to specify paths for applications deployed on JBoss EAP. On Linux the path
is: vfs: /co ntent/application.war. On Microsoft Windows it is:
vfs: /${user. d i r}/co ntent/application.war .
For example:
grant codeBase "vfs:/content/application.war/-" {
permission java.util.PropertyPermission "*", "read";
};
307
3. Ed it an exist in g p o licy
Select the policy from the list of existing policies, and select the Ed i t P o l i cy Entry
button. Edit the parameters as needed.
4. D elet e an exist in g p o licy.
Select the policy from the list of existing policies, and select the R emo ve P o l i cy Entry
button.
Report a bug
14 .1.7. Run JBoss EAP 6 Wit hin t he Java Securit y Manager

From JBoss EAP 6.4 and onwards, running JBoss EAP 6 within the Java Security Manager (JSM) is
done using the secmg r option.
Important
D irect usage of the -D java. securi ty. manag er Java system property is no longer
possible. This previous method used in older versions of JBoss EAP 6 to enable the Java
Security Manager is now only supported as a fallback mechanism in the JBoss EAP startup
scripts.
Note
From JBoss EAP 6.4 and onwards, custom security managers cannot be used.
The following procedure guides you through the steps of configuring your JBoss EAP 6 instance to
run within the Java Security Manager using a specified security policy.
Prereq u isit es
Before you follow this procedure, you need to write a security policy using the po l i cyto o l
application which is included in the Java D evelopment Kit (JD K) or the Java SE Runtime
Environment (JRE). Alternatively, you can write a security policy using a text editor.
Security policies will be needed for any user deployments that require permissions. This
procedure assumes that your policy is located at EAP_HOME/bi n/server. po l i cy.
The domain or standalone server must be completely stopped before you edit any configuration
files.
If you are using JBoss EAP 6 in a Managed D omain, you must perform the following procedure on
each physical host or instance in your domain.
Pro ced u re 14 .5. C o n f ig u re t h e Java Secu rit y Man ag er f o r JB o ss EAP 6
1. O p en t h e C o n f ig u rat io n File
Open the configuration file for editing. The configuration file you need to edit depends on
whether you use a Managed D omain or standalone server, as well as your operating system.
308
Chapt er 1 4 . JVM
A. Man ag ed D o main
For Linux: EAP_HOME/bi n/d o mai n. co nf
For Windows: EAP_HOME\bi n\d o mai n. co nf. bat
B. St an d alo n e Server
For Linux: EAP_HOME/bi n/stand al o ne. co nf
For Windows: EAP_HOME\bi n\stand al o ne. co nf. bat
2. En ab le t h e Java Secu rit y Man ag er
Use one of the methods below to enable the Java Security Manager:
A. Use the -secmg r option with your JBoss EAP 6 server startup script.
B. Uncomment the SEC MG R = "true" line in the configuration file:
A. O n Lin u x:
# Uncomment this to run with a security manager enabled
SECMGR="true"
B. O n Win d o ws:
rem # Uncomment this to run with a security manager enabled
set "SECMGR=true"
3. Sp ecif y t h e Java Secu rit y Po licy
You can use -D java. securi ty. po l i cy to specify the exact location of your security
policy. It should go onto one line only, with no line break. Using = = when setting D java. securi ty. po l i cy specifies that the security manager will use only the specified
policy file. Using = specifies that the security manager will use the specified policy combined
with the policy set in the po l i cy. url section of
JAVA_HOME/jre/l i b/securi ty/java. securi ty.
In your relevant JBoss EAP 6 configuration file, add your security policy Java options. If you
are using a Managed D omain, ensure that this is inserted before where
P R O C ESS_C O NT R O LLER _JAVA_O P T S and HO ST _C O NT R O LLER _JAVA_O P T S are set.
A. O n Lin u x:
JAVA_OPTS="$JAVA_OPTS Djava.security.policy==EAP_HOME/bin/server.policy Djboss.home.dir=EAP_HOME"
B. O n Win d o ws:
set "JAVA_OPTS=%JAVA_OPTS% Djava.security.policy==EAP_HOME\bin\server.policy Djboss.home.dir=EAP_HOME"
309
4. St art t h e D o main o r Server

Start the domain or server as normal.
Report a bug
14 .1.8. IBM JDK and t he Java Securit y Manager

Some versions of the IBM JD K use a default policy provider which does not work correctly with a
JBoss EAP security policy. If you are having problems using an IBM JD K to host JBoss EAP with the
Java Security Manager enabled, you must change the JRE configuration to use the standard policy
provider.
To modify the JRE configuration for the IBM JD K, edit the
JAVA_HO ME/jre/l i b/securi ty/java. securi ty file, and set the po l i cy. pro vi d er value to
sun. securi ty. pro vi d er. P o l i cyFi l e.
policy.provider=sun.security.provider.PolicyFile
Report a bug
14 .1.9. Debug Securit y Manager Policies

You can enable debugging information to help you troubleshoot security policy-related issues. The
java. securi ty. d ebug option configures the level of security-related information reported. The
command java -D java. securi ty. d ebug = hel p will produce help output with the full range of
debugging options. Setting the debug level to al l is useful when troubleshooting a security-related
failure whose cause is completely unknown, but for general use it will produce too much information.
A sensible general default is access: fai l ure.
Pro ced u re 14 .6 . En ab le g en eral d eb u g g in g
T h is p ro ced u re will en ab le a sen sib le g en eral level o f secu rit y- relat ed d eb u g
in f o rmat io n .
Add the following line to the server configuration file.
If the JBoss EAP 6 instance is running in a managed domain, the line is added to the
bi n/d o mai n. co nf file for Linux or the bi n\d o mai n. co nf. bat file for Windows.
If the JBoss EAP 6 instance is running as a standalone server, the line is added to the
bi n/stand al o ne. co nf file for Linux, or the bi n\stand al o ne. co nf. bat file for
Windows.
Li nux
JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=access:failure"
Wi nd o ws
set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.debug=access:failure"
R esu lt
A general level of security-related debug information has been enabled.
310
Chapt er 1 4 . JVM
Report a bug
311
Chapter 15. Web Subsystem

15.1. Configure t he Web Subsyst em
The Web subsystem can be configured using the Management Console or the Management CLI.
In the Management Console, click the C o nfi g urati o n tab at the top of the screen, expand the
Subsystems menu and then expand the Web menu. Click on the Servl et/HT T P menu item to
configure G l o bal settings, also the JSP , C o nnecto r and Vi rtual Servers settings. Click on the
Web Servi ces menu item to configure the web services subsystem.
In the Management CLI, all Web Subsystem parameters are configured using the standard command
format.
Note
The mo d _cl uster component is only available if your profile is ha or ful l -ha, in a
managed domain, or if you start your standalone server with the stand al o ne-ha or
stand al o ne-ful l -ha profile. For details of mo d _cl uster configuration see
Section 17.6.2, Configure the mo d _cl uster Subsystem .
Report a bug
15.2. Configure t he HT T P Session T imeout

The HTTP session timeout defines the period after which a HTTP session is considered to have
become invalid because there was no activity within the specified period. Changing the HTTP
session timeout requires that all affected JBoss EAP instances be restarted. Until that is done, the
original HTTP session timeout value applies.
The HTTP session timeout can be configured in several places. In order of precedence these are:
Application - defined in the application's web. xml configuration file. For details see Configure the
HTTP Timeout per Application in the Development Guide
Server - specified via the d efaul t-sessi o n-ti meo ut attribute. This setting is only available
from JBoss EAP 6.4.
D efault - 30 minutes.
Pro ced u re 15.1. C o n f ig u re t h e H T T P Sessio n T imeo u t u sin g t h e Man ag emen t C o n so le
1. Click the C o nfi g urati o n tab, then navigate to Subsystems, Web, and click on the
Servl et/HT T P menu item.
2. Click the G l o bal tab in the Servl et/HT T P C o nfi g urati o n panel.
3. Click the Ed i t option.
4. Enter the new value for the D efaul t sessi o n ti meo ut.
5. Click the Save button.
6. Reload the JBoss EAP server.
312
Chapt er 1 5. Web Subsyst em
Pro ced u re 15.2. C o n f ig u re t h e H T T P Sessio n T imeo u t u sin g t h e Man ag emen t C LI
Note
Add the prefix /ho st= HOST_NAME to the command for a managed domain.
1. Specify the desired HTTP Session Timeout value.
/subsystem=web:write-attribute(name=default-session-timeout,
value=ti meo ut)
2. Reload the JBoss EAP server.
reload
Report a bug
15.3. Servlet /HT T P Configurat ion

Pro ced u re 15.3. Servlet /H T T P C o n f ig u rat io n
1. In the Management Console, click the C o nfi g urati o n tab at the top of the screen, expand
the Subsystems menu and then expand the Web menu.
2. Click on the Servl et/HT T P menu item.
3. Click on the name of the component, then click on Ed i t.
4. Click the Ad vanced button to view advanced options.
Following are the advanced Servlet/HTTP configuration options.
If the Management CLI commands are to be applied to a profile, add the prefix /pro fi l e= PROFILE.
Examp le 15.1. C o n f ig u re t h e N ame o f t h is In st an ce

[domain@ localhost:9999 /] /profile=full-ha/subsystem=web:writeattribute(name=instance-id,value=wo rker1)
G lo b al C o n f ig u rat io n O p t io n s
D ef au lt Sessio n T imeo u t
Available from JBoss EAP 6.4. The web container's default session timeout.
Management CLI attribute: d efaul t-sessi o n-ti meo ut
D ef au lt Virt u al Server
The web container's default virtual server.
Management CLI attribute: d efaul t-vi rtual -server
313
In st an ce ID
The identifier used to enable session affinity in load balancing scenarios. The identifier
must be unique across all JBoss EAP servers in the cluster and is appended to the
generated session identifier. This allows the front-end proxy to forward the specific session
to the same JBoss EAP instance. The instance ID is not set as a default.
Management CLI attribute: i nstance-i d
N at ive
Add the native initialization listener to the web container.
Management CLI attribute: nati ve. Values: true or fal se. D efault: true.
JSP C o n f ig u rat io n O p t io n s
C h eck In t erval
Interval at which to check for JSP updates using a background thread, specified in
seconds. D efault: 0 , which means d i sabl ed .
Management CLI attribute: check-i nterval
D evelo p men t
If true, enables D evelopment Mode, which produces more verbose debugging information.
D efault: fal se.
Management CLI attribute: d evel o pment
D isab led
If true, the Java ServerPages (JSP) container is disabled. This is useful if you do not use
any JSPs. D efault: fal se.
Management CLI attribute: d i sabl ed
D isp lay So u rce Frag men t
If true, the JSP source fragment is displayed when a runtime error occurs. D efault: true.
Management CLI attribute: d i spl ay-so urce-frag ment
D u mp SMAP
If true, JSR 045 SMAP data is written to a file. D efault: fal se
Management CLI attribute: d ump-smap
G en erat e St rin g s as C h ar Arrays
If true, string constants are generated as char arrays. D efault: fal se
Management CLI attribute: g enerate-stri ng s-as-char-arrays
Erro r o n U se B ean In valid C lass At t rib u t e
If true, enables the output of errors when a bad class is used in useBean. D efault: fal se
Management CLI attribute: erro r-o n-use-bean-i nval i d -cl ass-attri bute
314
Java En co d in g
Specifies the encoding used for Java sources. D efault: UT F8
Management CLI attribute: java-enco d i ng
K eep G en erat ed
If true, keeps generated Servlets. D efault: true.
Management CLI attribute: keep-g enerated
Map p ed File
If true, static content is generated with one print statement per input line, to ease
debugging. D efault: true.
Management CLI attribute: true
Mo d if icat io n T est In t erval
Minimum amount of time between two tests for updates, specified in seconds. D efault: 4
Management CLI attribute: mo d i fi cati o n-test-i nterval
R eco mp ile o n Fail
If true, failed JSP compilations will be retried on each request. D efault: fal se.
Management CLI attribute: reco mpi l e-o n-fai l
Scrat ch D irect o ry
Specifies the location of a different work directory.
Management CLI attribute: scratch-d i r
SMAP
If true, JSR 045 SMAP is enabled. D efault: true
Management CLI attribute: smap
So u rce VM
Java development kit version with which the source files are compatible. D efault: 1. 5
Management CLI attribute: so urce-vm
T ag Po o lin g
If true, tag pooling is enabled. D efault: true
Management CLI attribute: tag -po o l i ng
T arg et VM
Java development kit version with which the class files are compatible. D efault: 1. 5
Management CLI attribute: targ et-vm
T rim Sp aces
Trim some spaces from the generated Servlet. D efault: fal se.
315
Trim some spaces from the generated Servlet. D efault: fal se.
Management CLI attribute: tri m-spaces
X Po wered B y
If true, the JSP engine is advertised using the x-po wered -by HTTP header. D efault:
true.
Management CLI attribute: x-po wered -by
Use one of the following commands to view the settings for either of these connectors:
[standalone@ localhost:9999 /] /subsystem=web/connector=http:readresource-description
[standalone@ localhost:9999 /] /subsystem=web/connector=ajp:read-resourcedescription
To configure a connector, select the C o nnecto rs tab and click Ad d . To remove a connector, select
its entry and click R emo ve. To edit a connector, select its entry and click Ed i t.
When you create a new connector using the Management CLI, its options are all set at once, as in the
following command:
Examp le 15.2. C reat e a N ew C o n n ect o r

[domain@ localhost:9999 /] /profile=fullha/subsystem=web/connector=ajp/:add(socketbinding=ajp,scheme=http,protocol=AJP/1.3,secure=false,name=ajp,maxpost-size=2097152,enabled=true,enable-lookups=false,redirectport=8433,max-save-post-size=4096)
D ef au lt C o n n ect o r at t rib u t es
B yt es Sen t
The number of byte sent by the connector.
Management CLI attribute: bytesSent
Pro xy Po rt
The port that will be used when sending a redirect.
Management CLI attribute: pro xy-po rt
Secu re
Indicates if content sent or received by the connector is secured from the user perspective.
D efault: fal se.
Management CLI attribute: secure
Virt u al Server
The list of virtual servers that can be accessed through this connector. D efault: Allow all
316
virtual servers.
Management CLI attribute: vi rtual -server
Erro r C o u n t
Number of errors that occur when processing requests by the connector.
Management CLI attribute: erro rC o unt
Maximu m T ime
Maximum time spent to process a request.
Management CLI attribute: maxT i me
So cket B in d in g
The named socket binding to which the connector is to be bound. A socket binding is a
mapping between a socket name and a network port. Socket bindings are configured for
each standalone server, or via socket binding groups in a managed domain. A socket
binding group is applied to a server group.
Management CLI attribute: so cket-bi nd i ng
Sch eme
The web connector scheme (such as HTTP or HTTPS).
Management CLI attribute: scheme
N ame
A unique name for the connector.
Management CLI attribute: name
Maximu m Po st Siz e
Maximum size in bytes of a POST request that can be parsed by the container. D efault:
20 9 7152
Management CLI attribute: max-po st-si ze
R eq u est C o u n t
Number of the request processed by the connector.
Management CLI attribute: req uestC o unt
Pro xy N ame
The host name that will be used when sending a redirect. D efault: nul l .
Management CLI attribute: pro xy-name
En ab led
D efines whether the connector is started on startup. D efault: true
Management CLI attribute: enabl ed
Pro t o co l
317
The web connector protocol to use, either AJP or HTTP. For each protocol you can either
specify the API and leave it to the server to determine which implementation is used, or
specify the fully-qualified class name.
Management CLI attribute: pro to co l
HTTP
API options: HT T P /1. 1 or HT T P /1. 0 .
If the client does not support HTTP/1.1, the connector will return HTTP/1.1 in its
initial response, then fall back to HTTP/1.0.
Fu lly Q u alif ied C o n n ect o r N ame o p t io n s:
JIO: o rg . apache. co yo te. http11. Http11P ro to co l
NIO2: o rg . apache. co yo te. http11. Http11Ni o P ro to co l
APR: o rg . apache. co yo te. http11. Http11AprP ro to co l
AJP
API option: AJP /1. 3
Fu lly Q u alif ied C o n n ect o r N ame o p t io n s:
JIO: o rg . apache. co yo te. ajp. AjpP ro to co l
APR: o rg . apache. co yo te. ajp. AjpAprP ro to co l
Note
APR requires the Native Components package be installed and active. For
detailed instructions on how to do so, see the JBoss EAP Installation Guide.
En ab le Lo o ku p s
Enable D NS lookups for the Servlet API.
Management CLI attribute: enabl e-l o o kups
Execu t o r
The name of the executor that should be used for the processing threads of this connector.
If undefined defaults to using an internal pool.
Management CLI attribute: executo r
Pro cessin g T ime
Processing time used by the connector, measured in milliseconds.
Management CLI attribute: pro cessi ng T i me
Pro xy B in d in g
318
The socket binding to define the host and port that will be used when sending a redirect.
D efault: nul l .
Management CLI attribute: pro xy-bi nd i ng
R ed irect Po rt
The port for redirection to a secure connector. D efault: 4 4 3
D efers to red i rect-bi nd i ng when set concurrently.
Management CLI attribute: red i rect-po rt
B yt es R eceived
Number of bytes received by the connector (POST data).
Management CLI attribute: bytesR ecei ved
R ed irect B in d in g
Redirect binding is similar to redirect port in terms of behavior except that it requires
specification of a socket-binding name in value instead of a port number. The red i rectbi nd i ng option provides higher configuration flexibility because it allows the use of predefined socket binding (https, AJP etc.) to the specific port for redirection. It gives the same
results as red i rect-po rt option.
Takes precedence over red i rect-po rt when set concurrently.
Management CLI attribute: red i rect-bi nd i ng
Maximu m C o n n ect io n s
The maximum number of concurrent connections that can be processed by the connector
with optimum performance. The default value depends on the connector used.
Management CLI attribute: max-co nnecti o ns
Maximu m Save Po st Siz e
Maximum size in bytes of a POST request that will be saved during certain authentication
schemes. D efault: 4 0 9 6 .
Management CLI attribute: max-save-po st-si ze
To configure virtual servers, click the Vi rtual Servers tab. Use the Ad d button to add a new
virtual server. To edit or remove a virtual server, select its entry and click the Ed i t or R emo ve button.
When you add a new virtual server using the Management CLI, all required options are set at once,
as in the following command.
Examp le 15.3. Ad d a N ew Virt u al Server

/profile=full-ha/subsystem=web/virtual-server=default-host/:add(enablewelcome-root=true,default-web-module=ROOT.war,alias=
["localhost","example.com"],name=default-host)
Virt u al Servers O p t io n s
319
Access Lo g
The element describing how the access log information must be logged.
Management CLI attribute: access-l o g
To add access-l o g attribute enter the following management CLI command:
/subsystem=web/virtual-server=default-host/configuration=accesslog:add()
The access-l o g attribute has several child attributes. To list these children and their
configuration options, enter the following management CLI command:
/subsystem=web/virtual-server=default-host/configuration=accesslog:read-resource-description()
p at t ern
A formatting layout identifying the various information fields from the request
and response to be logged, or the word co mmo n or co mbi ned to select a
standard format. Values for the pattern attribute are made up of format
tokens. If not specified, a default of co mmo n is used.
ro t at e
Tell the valve if it should rotate the ouput or not. If not specified, a default of
true is used.
p ref ix
D efine the prefix to be used to name the log file. If not specified, a default of
access_l o g is used.
ext en d ed
Uses the Extend ed AccessLo g Val ve instead the AccessLo g Val ve. If not
specified, a default of fal se is used.
reso lve- h o st s
Tell the valve whether to resolve the host names or not. If not specified, a
default of fal se is used. Unless the l o o kups on the connector for reso l veho st is enabled, this option will not work. This can be enabled by setting
reso l ve-ho st to true.
Alias
A list of hostnames supported by this virtual server. In the Management Console, use one
hostname per line.
Management CLI attribute: al i as
D ef au lt Web Mo d u le
The module whose web application will be deployed at the root node of this virtual server,
and will be displayed when no directory is given in the HTTP request. D efault: R O O T . war
Management CLI attribute: d efaul t-web-mo d ul e
320
En ab le Welco me R o o t
This element defines whether or not the bundled welcome directory is used as the root web
context. D efault: fal se
Management CLI attribute: enabl e-wel co me-ro o t
N ame
A unique name for the virtual server, for display purposes.
Management CLI attribute: name
R ewrit e
The element describing what the rewrite valve must do with requests corresponding to the
virtual host. rewri te describes how requests would be rewritten before processing. It adds
the R ewri teVal ve to the Virtual Host defined by vi rtual -server.
f lag
A R ewri teR ul e can have its behavior modified by one or more flags. Flags are
included in square brackets at the end of the rule, and multiple flags are
separated by commas.
p at t ern
Pattern is a perl compatible regular expression, which is applied to the URL of the
request.
su b st it u t io n
The substitution of a rewrite rule is the string which is substituted for (or replaces)
the original URL which Pattern matched.
Management CLI attribute: rewri te
SSO
SSO configuration for this virtual server. D efault (in case of http): true.
Management CLI attribute: sso
To add SSO configuration, enter the following management CLI command:
/subsystem=web/virtual-server=defaulthost/configuration=sso:add()
The SSO attribute has several child attributes. To list these children and their
configuration options, enter the following management CLI command:
/subsystem=web/virtual-server=defaulthost/configuration=sso:read-resource-description()
h t t p - o n ly
The cookie http-o nl y flag will be set.
cach e- co n t ain er
321
Enables clustered SSO using the specified clustered cache container.

reau t h en t icat e
Enables reauthentication with the realm when using SSO .
d o main
The cookie domain that will be used.
cach e- n ame
Name of the cache to use in the cache container.
Report a bug
15.4 . Replace t he Default Welcome Web Applicat ion

JBoss EAP 6 includes a Welcome application, which displays when you open the URL of the server
at port 8080. You can replace this application with your own web application by following this
procedure.
Pro ced u re 15.4 . R ep lace t h e D ef au lt Welco me Web Ap p licat io n Wit h Yo u r O wn Web
Ap p licat io n
1. D isab le t h e Welco me ap p licat io n .
Use the Management CLI script EAP_HOME/bi n/jbo ss-cl i . sh to run the following
command. You may need to change the profile to modify a different managed domain profile,
or remove the /pro fi l e= d efaul t portion of the command for a standalone server.
/profile=default/subsystem=web/virtual-server=default-host:writeattribute(name=enable-welcome-root,value=false)
2. C o n f ig u re yo u r Web ap p licat io n t o u se t h e ro o t co n t ext .
To configure your web application to use the root context (/) as its URL address, modify its
jbo ss-web. xml , which is located in the MET A-INF/ or WEB-INF/ directory. Replace its
<co ntext-ro o t> directive with one that looks like the following.
<jboss-web>
<context-root>/</context-root>
</jboss-web>
3. D ep lo y yo u r ap p licat io n .
D eploy your application to the server group or server you modified in the first step. The
application is now available on http: //SERVER_URL:PORT/.
Report a bug
15.5. Syst em Propert ies in JBossWeb
322
This section lists the system properties that may be used to modify the default JBossWeb behavior.
The system-properties can be set in the JBoss Enterprise Web Application configuration. You must
restart it to get them applied to the web sub system.
Following is an example on how to modify the system-properties in JBossWeb
standalone@ localhost:9999 /] ./systemproperty=org.apache.catalina.JSESSIONID:add(value="MYID")
standalone@ localhost:9999 /] shutdown
Communication error: Channel closed
Closed connection to localhost:9999
For some properties, you can restart it using a reload command.
Following is an example to restart using a reload command.
[standalone@ localhost:9999 /] reload
{
}
}
T ab le 15.1. Servlet co n t ain er an d co n n ect o rs
At t rib u t e
D escrip t io n
jvmRoute
Provides a default value for the jvmRoute

attribute. It does not override the automatically
generated value used when using ha read with
using configuration like standalone-ha.xml
It supports rel o ad .
org.apache.tomcat.util.buf.StringCache.byte.en
abled
If true, the String cache is enabled for

ByteChunk. If the value is not specified, the
default value of false is used.
org.apache.tomcat.util.buf.StringCache.char.en If true, the String cache is enabled for
abled
CharChunk. If the value is not specified, the
org.apache.tomcat.util.buf.StringCache.cacheSi The size of the String cache. If the value is not
ze
specified, the default value of 5000 is used.
org.apache.tomcat.util.buf.StringCache.maxStri The maximum length of String that will be
ngSize
cached. If the value is not specified, the default
value of 128 is used.
org.apache.tomcat.util.http.FastHttpD ateFormat. The size of the cache to use parsed and
CACHE_SIZ E
formatted date value. If the value is not specified,
the default value of 1000 is used.
org.apache.catalina.core.StandardService.D EL If true, the connector startup is not done
AY_CONNECTOR_STARTUP
automatically. It is useful in embedded mode.
323
At t rib u t e
D escrip t io n
org.apache.catalina.connector.Request.SESSI
ON_ID _CHECK
If true, the Servlet container verifies that a

session exists in a context with the specified
session id before creating a session with that id.
If true, custom HTTP status messages are used
within HTTP headers. Users must ensure that
any such message is ISO-8859-1 encoded,
particularly if user provided input is included in
the message, to prevent a possible XSS
vulnerability. If value is not specified the default
value of false is used.
The maximum amount of parameters that can be
parsed in a post body. If exceeded, parsing fails
using an IllegalStateException. The default
value is 512 parameters.
The maximum amount of headers that can be
sent in the HTTP request. If exceeded, parsing
will fail using an IllegalStateException. The
default value is 128 headers.
The maximum number of threads a connector is
going to use to process requests. The default
value is 32 x
Runtime.getRuntime().availableProcessors().
(512 x
Runtime.getRuntime().availableProcessors() for
the JIO connector)
The maximum size of the HTTP headers, in
bytes. If exceeded, parsing will fail using an
ArrayOutOfBoundsExceptions. The default
value is 8192 bytes.
Allows using simple compression with the HTTP
connector. The default value is off, and
compression can be enabled using the value on
to enable it conditionally, or force to always
enable it.
User agents regexps that will not receive
compressed content. The default value is empty.
Content type prefixes of compressible content.
The default value is text/html,text/xml,text/plain.
Minimum size of content that will be compressed.
The default value is 2048 bytes.
D efault socket timeout. The default value is
60000 ms.
Use this property to remove . java and . cl ass
files to ensure that JSP sources are recompiled.
The default value is fal se. D efault socket
timeout for keep alive. The default value is -1 ms,
which means it will use the default socket
timeout.
Specifies the number of times to Stri ng () must
be invoked before activating cache. The default
value is 10 0 0 0 0 .
org.apache.coyote.Constants.USE_CUSTOM_S
TATUS_MSG_IN_HEAD ER
org.apache.tomcat.util.http.Parameters.MAX_CO
UNT
org.apache.tomcat.util.http.MimeHeaders.MAX_
COUNT
org.apache.tomcat.util.net.MAX_THREAD S
org.apache.coyote.http11.Http11Protocol.MAX_
HEAD ER_SIZ E
org.apache.coyote.http11.Http11Protocol.COMP
RESSION
RESSION_RESTRICTED _UA
RESSION_MIME_TYPES
RESSION_MIN_SIZ E
org.apache.coyote.http11.D EFAULT_CONNECTI
ON_TIMEOUT
org.jboss.as.web.deployment.D ELETE_WORK_
D IR_ONCONTEXTD ESTROY
org.apache.tomcat.util.buf.StringCache.trainThr
eshold
T ab le 15.2. EL
324
At t rib u t e
D escrip t io n
org.apache.el.parser.COERCE_TO_Z ERO
If true, when coercing expressions to numbers " "

and null will be coerced to zero as required by
the specification. If value is not specified, the
default value of true is used.
T ab le 15.3. JSP
At t rib u t e
D escrip t io n
org.apache.jasper.compiler.Generator.VAR_EXP The name of the variable to use for the

RESSIONFACTORY
expression language expression factory. If
value is not specified, the default value of
_el_expressionfactory is used.
org.apache.jasper.compiler.Generator.VAR_INS The name of the variable to use for the instance
TANCEMANAGER
manager factory. If value is not specified, the
default value of _jsp_instancemanager is used.
org.apache.jasper.compiler.Parser.STRICT_QU If false, the requirements for escaping quotes in
OTE_ESCAPING
JSP attributes are relaxed so that a missing
required quote does not cause an error. If value
is not specified, the specification compliant
default of true is used.
org.apache.jasper.Constants.D EFAULT_TAG_B Any tag buffer that expands beyond
UFFER_SIZ E
org.apache.jasper.Constants.D EFAULT_TAG_B
UFFER_SIZ E is destroyed and a new buffer is
created of the default size. If value is not
specified, the default value of 512 is used.
org.apache.jasper.runtime.JspFactoryImpl.USE If true, a ThreadLocal PageContext pool is used.
_POOL
If value is not specified, the default value of true
is used.
org.apache.jasper.runtime.JspFactoryImpl.POO The size of the ThreadLocal PageContext. If
L_SIZ E
value is not specified, the default value of 8 is
used.
org.apache.jasper.Constants.JSP_SERVLET_B The base class of the Servlets generated from
ASE
the JSPs. If value is not specified, the default
value of org.apache.jasper.runtime.HttpJspBase
is used.
org.apache.jasper.Constants.SERVICE_METHO The name of the service method called by the
D _NAME
base class. If value is not specified, the default
value of _jspService is used.
org.apache.jasper.Constants.SERVLET_CLASS The name of the ServletContext attribute that
PATH
provides the classpath for the JSP. If value is
not specified, the default value of
org.apache.catalina.jsp_classpath is used.
org.apache.jasper.Constants.JSP_FILE
The name of the request attribute for <jsp-file>
element of a servlet definition. If present on a
request, this overrides the value returned by
request.getServletPath() to select the JSP page
to be executed. If value is not specified, the
default value of org.apache.catalina.jsp_file is
used.
325
At t rib u t e
D escrip t io n
org.apache.jasper.Constants.PRECOMPILE
The name of the query parameter that causes

the JSP engine to just pregenerate the servlet
but not invoke it. If value is not specified, the
default value of
org.apache.catalina.jsp_precompile is used.
org.apache.jasper.Constants.JSP_PACKAGE_N The default package name for compiled jsp
AME
pages. If value not specified, the default value of
org.apache.jsp is used.
org.apache.jasper.Constants.TAG_FILE_PACKA The default package name for tag handlers
GE_NAME
generated from tag files. If value is not specified,
the default value of org.apache.jsp.tag is used.
org.apache.jasper.Constants.TEMP_VARIABLE_ Prefix to use for generated temporary variable
NAME_PREFIX
names. If value is not specified, the default value
of _jspx_temp is used.
org.apache.jasper.Constants.USE_INSTANCE_ If true, the instance manager is used to obtain
MANAGER_FOR_TAGS
tag handler instances. If value is not specified,
true is used.
org.apache.jasper.Constants.INJECT_TAGS
If true, annotations specified in tags will be
processed and injected. This can have a
performance impact when using simple tags, or
if tag pooling is disabled. If value is not
specified, false is used.
T ab le 15.4 . Secu rit y
At t rib u t e
D escrip t io n
org.apache.catalina.connector.RECYCLE_FACA
D ES
If this is true or if a security manager is in use a

new facade object is created for each request. If
value is not specified, the default value of false
is used.
org.apache.catalina.connector.CoyoteAdapter.A If this is true the '\' character is permitted as a
LLOW_BACKSLASH
path delimiter. If value is not specified, the
org.apache.tomcat.util.buf.UD ecoder.ALLOW_E If this is true '% 2F' and '% 5C' is permitted as
NCOD ED _SLASH
path delimiters. If value is not specified, the
T ab le 15.5. Sp ecif icat io n
At t rib u t e
326
D escrip t io n
At t rib u t e
D escrip t io n
org.apache.catalina.STRICT_SERVLET_COMPL If value is not specified, true is used. If this is

IANCE
true the following actions will occur:
any wrapped request or response object
passed to an application dispatcher is
checked to ensure that it has wrapped the
original request or response. (SRV.8.2 /
SRV.14.2.5.1)
a call to Response.getWriter() if no character
encoding has been specified results in
subsequent calls to
Response.getCharacterEncoding() returning
ISO-8859-1 and the Content-Type response
header will include a charset=ISO-8859-1
component. (SRV.15.2.22.1)
every request that is associated with a
session causes the session's last accessed
time to be updated regardless of whether or
not the request explicity accesses the
session. (SRV.7.6)
org.apache.catalina.core.StandardWrapperValv If true or if
e.SERVLET_STATS
org.apache.catalina.STRICT_SERVLET_COMPL
IANCE is true, the wrapper will collect the JSR-77
statistics for individual servlets. If value is not
specified, the default value of false is used.
org.apache.catalina.session.StandardSession. If this is true or if
ACTIVITY_CHECK
org.apache.catalina.STRICT_SERVLET_COMPL
IANCE is true Tomcat tracks the number of active
requests for each session. When determining if a
session is valid, any session with at least one
active request is always be considered valid. If
value is not specified, the default value of false
is used.
Report a bug
15.6. About ht t p-only Session Management Cookies

The http-o nl y attribute for session management cookies mitigates the risk of security
vulnerabilities by restricting access from non-HTTP APIs (such as JavaScript). This restriction helps
mitigate the threat of session cookie theft via cross-site scripting attacks. On the client side, the
cookies cannot be accessed using JavaScript or other scripting methods. This applies only to
session management cookies and not other browser cookies. By default, the http-o nl y attribute is
enabled.
You need to add SSO to the virtual server in the web subsystem to use the http-o nl y attribute.
Examp le 15.4 . Ad d SSO t o t h e Virt u al Server
327
Enter the following Management CLI command to add SSO to the virtual server in the web
subsystem.
/subsystem= web/vi rtual -server= d efaul t-ho st/sso = co nfi g urati o n: ad d
Note
JSESSIONID and JSESSIONID SSO are session tracking cookies. By default, they are httpo nl y and must not be accessed by scripts.
Examp le 15.5. Verif y t h e http-o nl y At t rib u t e

Enter the following Management CLI command to verify the value of the http-o nl y attribute.
/subsystem= web/vi rtual -server= d efaul t-ho st/sso = co nfi g urati o n: read reso urce-d escri pti o n
{
"result" => {
"description" => "The SSO configuration for this virtual
server.",
"access-constraints" => {"sensitive" => {"web-sso" => {"type"
=> "web"}}},
"attributes" => {
"http-only" => {
"type" => BOOLEAN,
"description" => "The cookie http-only flag will be
set.",
"expressions-allowed" => true,
"nillable" => true,
"default" => true,
"access-type" => "read-write",
"storage" => "configuration",
"restart-required" => "all-services"
}
...
}
}
Examp le 15.6 . En ab le t h e http-o nl y At t rib u t e

Enter the following Management CLI command to enable the http-o nl y attribute.
/subsystem= web/vi rtual -server= d efaul t-ho st/sso = co nfi g urati o n: wri teattri bute(name= http-o nl y,val ue= true)
Report a bug
328
Chapter 16. Web Services Subsystem

16.1. Configure Web Services Opt ions
The Web Services options can be configured using the Management Console or the Management
CLI.
In the Management Console, click the C o nfi g urati o n tab at the top of the screen, expand the
Subsystems menu and then expand the Web menu. Click on the Web Servi ces menu item to
configure the web services subsystem. The options are explained in the table below.
T ab le 16 .1. Web Services C o n f ig u rat io n O p t io n s
O p t io n
D escrip t io n
Modify WSD L Address
Whether the WSD L address can

be modified by applications.
D efaults to true.
WSD L Host
WSD L Port
The WSD L contract of a JAXWS Web Service includes a

<soap:address> element which
points to the location of the
endpoint. If the value of
<soap:address> is a valid URL,
it is not overwritten unless
mo d i fy-wsd l -ad d ress is
set to true. If the value of
<soap:address> is not a valid
URL, it is overwritten using the
values of wsd l -ho st and
either wsd l -po rt or wsd l secure-po rt. If wsd l -ho st is
set to
jbo ssws. und efi ned . ho st,
the requester's host address is
used when the <soap-address>
is rewritten. D efaults to
${jbo ss. bi nd . ad d ress: 12
7. 0 . 0 . 1}, which uses
127. 0 . 0 . 1 if no bind address
is specified when JBoss EAP 6
is started.
The non-secure port that is
used to rewrite the SOAP
address. If this is not set (the
default), the port is identified by
querying the list of installed
connectors.
C LI C o mman d
/profile=fullha/subsystem=webservi
ces/:writeattribute(name=modif
y-wsdladdress,value=true)
ces/:writeattribute(name=wsdlhost,value=127.0.0.1)
ces/:writeattribute(name=wsdlport,value=80)
329
O p t io n
D escrip t io n
WSD L Secure Port
The secure port that is used to

rewrite the SOAP address. If
this is not set (the default), the
port is identified by querying
the list of installed connectors.
C LI C o mman d
ces/:writeattribute(name=wsdlsecureport,value=443)
Note
You may need to change the profile to modify a different managed domain profile, or remove
the /profile=full-ha part of the command for a standalone server.
Web Services Su b syst em

To enable logging with Apache CXF, configure the following system property in
stand al o ne/d o mai n. xml file:
<system-properties>
<property name="org.apache.cxf.logging.enabled" value="true"/>
</system-properties>
Report a bug
16.2. Overview of Handlers and Handler Chains

Each endpoint config may be associated with P R E and P O ST handler chains. Each handler chain
may include JAXWS-compliant handlers. For outbound messages, PRE handler chain handlers are
executed before any handler attached to the endpoints using standard JAXWS means, such as the
@ Hand l erC hai n annotation. POST handler chain handlers are executed after usual endpoint
handlers. For inbound messages, the opposite applies. JAX-WS is a standard API for XML-based
web services, and is documented at http://jcp.org/en/jsr/detail?id=224.
A handler chain may also include a pro to co l -bi nd i ng s attribute, which sets the protocols which
trigger the chain to start.
A JAXWS handler is a child element hand l er within a handler chain. The handler takes a cl ass
attribute, which is the fully-qualified classname of the handler class. When the endpoint is deployed,
an instance of that class is created for each referencing deployment. Either the deployment class
loader or the class loader for module o rg . jbo ss. as. webservi ces. server. i nteg rati o n
must be able to load the handler class.
Pro ced u re 16 .1. H o w t o ad d h an d ler- ch ain s an d h an d lers via t h e C LI
1. Start the JBoss EAP CLI
EAP_HOME/bin/jboss-cli.sh
2. Add handler chain and handlers via JBoss CLI:
330
Chapt er 1 6 . Web Services Subsyst em
Examp le 16 .1. Ad d a h an d ler ch ain

[standalone@ localhost:9999 /] /subsystem=webservices/endpointconfig=Standard-Endpoint-Config/post-handler-chain=myhandlers:add(protocol-bindings="##SOAP11_HTTP")
Examp le 16 .2. Ad d a h an d ler

[standalone@ localhost:9999 /] /subsystem=webservices/endpointconfig=Standard-Endpoint-Config/post-handler-chain=myhandlers/handler=foohander:add(class="org.jboss.ws.common.invocation.RecordingServerH
andler")
Examp le 16 .3. Ad d a h an d ler

[standalone@ localhost:9999 /] /subsystem=webservices/endpointconfig=Standard-Endpoint-Config/post-handler-chain=myhandlers/handler=barhandler:add(class="com.arjuna.webservices11.wsarj.handler.Instanc
eIdentifierInHandler")
3. Reload the server:

[standalone@ localhost:9999 /] reload
4. Confirm the handler-chain and handlers were added correctly:
Examp le 16 .4 . R ead a h an d ler- ch ain

/profile=default/subsystem=webservices/endpoint-config=StandardEndpoint-Config/post-handler-chain=my-handlers:read-resource
Examp le 16 .5. R ead a h an d ler

/profile=default/subsystem=webservices/endpoint-config=StandardEndpoint-Config/post-handler-chain=my-handlers/handler=barhandler:read-resource
The options used in the commands above can be modified as required to add or modify handlers.
The handlers available in JBoss EAP can be found in the API Documentation javadocs:
331
https://access.redhat.com/documentation/enUS/JBoss_Enterprise_Application_Platform/6.4/html/API_D ocumentation/files/javadoc/javax/xml/ws/h
andler/Handler.html
More information about handlers, handler-chains, endpoints and related issues can be also found in
the JBoss EAP Development Guide available at https://access.redhat.com/documentation/enUS/JBoss_Enterprise_Application_Platform
Report a bug
332
Chapt er 1 6 . Web Services Subsyst em
Chapter 17. HTTP Clustering and Load Balancing

17.1. HT T P Server name convent ions
The following tables outline the naming and location conventions used when discussing HTTPD related topics.
T ab le 17.1. Ap ach e H T T P Server p ro vid ed b y o p erat in g syst em
O p erat in g Syst em
HTTPD_CONF.D
HTTPD_CONF
HTTPD_MODULES
Red Hat Enterprise

Linux (httpd)
HPUX (Web Server
Suite)
/etc/httpd /co nf. d
/etc/httpd /co nf
See note below.
/o pt/hpws/apache/
co nf
/etc/httpd /mo d ul e
s
/o pt/hpws/apache/
mo d ul es
Note
There is no co nf. d in HP-UX's Web server Suite for Apache HTTP Server. You can create
one, however:
Pro ced u re 17.1. t it le
1. Create /o pt/hpws/apache/co nf. d .
2. Add Incl ud e co nf. d /*. co nf into the httpd . co nf file.
T ab le 17.2. JB o ss En t erp rise Web Server

O p erat in g
Syst em
HTTPD_CONF.D
HTTPD_CONF
HTTPD_MODULE
S
D ist rib u t io n
Red Hat
Enterprise Linux
Red Hat
Enterprise Linux
Solaris
/EWS_HOME/http
d /co nf. d
/etc/httpd /co
nf. d
/EWS_HOME/etc
/httpd /co nf. d
/EWS_HOME/http
d /co nf
/etc/httpd /co
nf
/EWS_HOME/etc
/httpd /co nf
zip
Windows
/EWS_HOME/etc
/httpd /co nf. d
/EWS_HOME/etc
/httpd /co nf
/EWS_HOME/http
d /mo d ul es
/usr/l i b/http
d /mo d ul es
/EWS_HOME/l i b
/httpd /mo d ul e
s
/EWS_HOME/l i b
/httpd /mo d ul e
s
rpm
zip
zip
333
Note
Pat h varian ces:
If you are using a 64-bit architecture, amend the filepaths from the table above to use the
l i b6 4 / directory.
If you are using a Red Hat Enterprise Linux 7 installation, the httpd directory is named
httpd 22.
Report a bug

17.2.1. About High-Availabilit y and Load Balancing Clust ers
Clustering refers to using multiple resources, such as servers, as though they were a single entity. The
two main types of clustering are Load balancing (LB) and High-availability (HA). In a LB cluster, all
resources run at the same time, and a management layer spreads the work load across them.
In HA clustering, one resource runs, and another is available to step in if the first one becomes
unavailable. The purpose of HA clustering is to reduce the consequences of hardware, software, or
network outages.
JBoss EAP 6 supports clustering at several different levels. Some of the components of the runtime
and your applications that can be made highly available are:
Instances of the Application Server
Web applications, when used in conjunction with the internal JBoss Web Server, Apache HTTP
Server, Microsoft IIS, or Oracle iPlanet Web Server.
Stateful, stateless, and entity Enterprise JavaBeans (EJBs)
Single Sign On (SSO) Mechanisms
D istributed cache
HTTP sessions
JMS services and Message-driven beans (MD Bs)
Clustering is made available to JBoss EAP 6 by two subsystems: jg ro ups and mo d cl uster. The
ha and ful l -ha profiles have these systems enabled. In JBoss EAP 6 these services start up and
shut down on demand, but they will only start up if an application configured as d i stri butabl e is
deployed on the servers.
Infinispan is provided as the cache provider in JBoss EAP 6. Infinispan manages clustering and
replication caches for JBoss EAP 6.
Report a bug
17.2.2. Component s Which Can Benefit from High Availabilit y

High Availability (HA) falls into a few broad categories in JBoss EAP 6.
334
Chapt er 1 7 . HT T P Clust ering and Load Balancing
T h e C o n t ain er
Several instances of JBoss EAP 6 (running as a standalone server) or a server group's members
(running as part of a managed domain) can be configured to be highly available. This means that if
one instance or member is stopped or disappears from the cluster, its work load is moved to a peer.
The work load can be managed in such a way to provide load-balancing functionality as well, so
that servers or server groups with more or better resources can take on a larger portion of the work
load, or additional capacity can be added during times of high load.
T h e Web Server
The web server itself can be clustered for HA, using one of several compatible load balancing
mechanisms. The most flexible is mo d _cl uster connector, which is tightly integrated with the JBoss
EAP 6 container. Other choices include Apache mo d _jk or mo d _pro xy connectors, or the ISAPI
connector and NSAPI connector.
T h e Ap p licat io n
D eployed applications can be made highly-available because of the Java Enterprise Edition 6 (Java
EE 6) specification. Stateless or stateful session EJBs can be clustered so that if the node which is
involved in the work disappears, another node can take over, and in the case of stateful session
beans, preserve the state.
Report a bug
17.2.3. Overview of HT T P Connect ors

JBoss EAP 6 has the ability to use load-balancing and high-availability mechanisms built into
external web servers, such as Apache Web Server, Microsoft IIS, and Oracle iPlanet. JBoss EAP 6
communicates with the external web server using a connector. These connectors are configured
within the web subsystem of JBoss EAP 6.
The web servers include software modules which control the way that HTTP requests are routed to
JBoss EAP 6 nodes. Each of these modules varies in how it works and how it is configured. The
modules are configured to balance work loads across multiple JBoss EAP 6 nodes, to move work
loads to alternate servers in case of a failure event, or both. These abilities are called Load Balancing
and High Availability (HA).
JBoss EAP 6 supports several different connectors. The one you choose depends on the web server
in use and the functionality you need.
The table below lists the differences between the different HTTP connectors which are compatible with
JBoss EAP 6. For the most current information about supported configurations for HTTP connectors,
see https://access.redhat.com/articles/111663.
T ab le 17.3. H T T P co n n ect o r f eat u res an d co n st rain t s
Con
n ect
or
Web server
Su p p o rt ed
Su p p o rt ed
o p erat in g syst ems p ro t o co ls
Ad ap t s t o d ep lo ymen t
st at u s
Su p p
o rt s
st ick
y
sessi
on
335
Con
n ect
or
Web server
Su p p o rt ed
Su p p o rt ed
o p erat in g syst ems p ro t o co ls
Ad ap t s t o d ep lo ymen t
st at u s
Su p p
o rt s
st ick
y
sessi
on
mod_ httpd in
cluste JBoss
r
Enterprise
Web Server,
httpd
provided by
operating
system (Red
Hat
Enterprise
Linux,
HewlettPackard HPUX)
mod_j httpd in
k
JBoss
Enterprise
Web Server,
httpd
provided by
operating
system (Red
Hat
Enterprise
Linux,
HewlettPackard HPUX)
mod_ httpd in
proxy JBoss
Enterprise
Web Server
Red Hat Enterprise

Linux, Microsoft
Windows Server,
Oracle Solaris,
Hewlett-Packard HPUX
HTTP,
HTTPS, AJP
Yes. D etects deployment and

undeployment of
applications and
dynamically decides whether
to direct client requests to a
server based on whether the
application is deployed on
that server.
Yes
Red Hat Enterprise

Linux, Microsoft
Windows Server,
Oracle Solaris,
Hewlett-Packard HPUX
AJP
No. D irects client requests to

the container as long as the
container is available,
regardless of application
status.
Yes
Red Hat Enterprise

Linux, Microsoft
Windows Server,
Oracle Solaris
HTTP,
HTTPS, AJP
Yes
ISAPI
conn
ector
Microsoft IIS
Microsoft Windows
Server
AJP
NSAP
I
conn
ector
Oracle
iPlanet Web
Server
Oracle Solaris
AJP

status.
status.
status.
Learn mo re ab o u t each H T T P C o n n ect o r

Section 17.6.1, About the mo d _cl uster HTTP Connector
Section 17.7.1, About the Apache mod_jk HTTP Connector
336
Yes
Yes
Section 17.8.1, About the Apache mod_proxy HTTP Connector

Section 17.9.1, About the Internet Server API (ISAPI)
Section 17.10.1, About the Netscape Server API (NSAPI)
JBoss EAP 6 supported configurations are available here: https://access.redhat.com/articles/111663.
Report a bug
17.2.4 . Node t ypes

H T T P co n n ect o r n o d e
A worker node, sometimes referred to as a node, is a JBoss EAP 6 server instance which accepts
requests from one or more client-facing HTTP servers that act as a proxy. JBoss EAP 6 can accept
HTTP, HTTPS and AJP requests from Apache HTTP Server, Microsoft IIS or Oracle iPlanet Web
Server (formerly Netscape Web Server).
For an overview of HTTP connectors supported by JBoss EAP 6 and how to configure them, see
Section 17.2.3, Overview of HTTP Connectors .
C lu st er n o d e
Cluster node is a specialization of the worker node. Such a cluster may be load-balancing, highavailability or both. In a load-balancing cluster, a central manager distributes work loads amongst
its nodes equally, by some situation-specific measurement of equality. In a high-availability cluster,
some nodes are actively doing work, and others are waiting to step in if one of the active nodes
leaves the cluster.
Examp le 17.1. Ap ach e H T T P Server wit h mo d _clu st er co n f ig u red

For instance, you might have a setup where Apache HTTP Server with mod_cluster configured
acts as a load-balancing proxy to client's requests. These requests are forwarded to particular
cluster nodes according to their current load. In case the sticky sessions are disabled, all
incoming requests are distributed according to the current load. In case sticky sessions are
enabled (default), subsequent requests within an already created session are routed to the worker
node with which the session was created. If one of these cluster nodes dies or becomes
overloaded, Apache HTTP Server with mod_cluster acting as a load-balancing proxy will forward
client's request to another cluster node. D ue to the session replication within the cluster, client's
data will not be lost.
Similarly, you might have a simpler setup with worker nodes that are not clustered. If a worker
node dies, its neighbor does not have the former session data, yet client will not get any non-HTTP
200 error code.
In the case of sticky session configuration, it does not matter to the load-balancing proxy whether
or not its worker nodes are clustered.
Report a bug
17.3. Connect or Configurat ion

17.3.1. Define T hread Pools for HT T P Connect or in JBoss EAP 6
337
Su mmary
Thread Pools in JBoss EAP 6 can be shared between different components using the Executor
model. These pools can be shared not only by different (HTTP) connectors, but also by other
components within JBoss EAP 6 that support the Executor model. Getting the HTTP connector thread
pool to match your current web performance requirements is tricky and requires close monitoring of
the current thread pool and the current and anticipated web load demands. In this task, you will learn
how to set the a thread pool for an HTTP Connector using the Executor model. You will learn how to
set this using both the Management CLI and by modifying the XML configuration file.
Note
If you are running JBoss EAP in domain mode, add the prefix /pro fi l e= PROFILE_NAME to
all Management CLI commands in this procedure.
Pro ced u re 17.2. Set u p a t h read p o o l f o r an H T T P C o n n ect o r

1. D ef in e a t h read f act o ry
Open up your configuration file (stand al o ne. xml if modifying for a standalone server or
d o mai n. xml if modifying for a domain based configuration. This file will be in the
EAP_HOME/stand al o ne/co nfi g urati o n or the EAP_HOME/d o mai n/co nfi g urati o n
folder).
Add the following subsystem entry, changing the values to suit your server requirements.
<subsystem xmlns="urn:jboss:domain:threads:1.1">
<thread-factory name="http-connector-factory" thread-namepattern="HTTP-%t" priority="9" group-name="uq-thread-pool"/>
</subsystem>
If you prefer to use the Management CLI to do this task, then execute the following command
in a CLI command prompt:
[standalone@ localhost:9999 /] ./subsystem=threads/threadfactory=http-connector-factory:add(thread-name-pattern="HTTP-%t",
priority="9", group-name="uq-thread-pool")
2. C reat e an execu t o r
You can use one of six in-built executor classes to act as the executor for this factory. The six
executors are:
unbo und ed -q ueue-thread -po o l : This type of thread pool always accepts tasks. If
fewer than the maximum number of threads are running, a new thread is started up to run
the submitted task; otherwise, the task is placed into an unbounded FIFO queue to be
executed when a thread is available.
338
Note
The single-thread executor type provided by
Executo rs. si ng l eT hread Executo r() is essentially an unbounded-queue
executor with a thread limit of one. This type of executor is deployed using the
unbo und ed -q ueue-thread -po o l -executo r element.
bo und ed -q ueue-thread -po o l : This type of executor maintains a fixed-length queue
and two pool sizes: a co re size and a maxi mum size. When a task is accepted, if the
number of running pool threads is less than the co re size, a new thread is started to
execute the task. If space remains in the queue, the task is placed in the queue. If the
number of running pool threads is less than the maxi mum size, a new thread is started to
execute the task. If blocking is enabled on the executor, the calling thread will block until
space becomes available in the queue. The task is delegated to the handoff executor, if a
handoff executor is configured. Otherwise, the task is rejected.
bl o cki ng -bo und ed -q ueue-thread -po o l : A thread pool executor with a bounded
queue where threads submittings tasks may block. Such a thread pool has a core and
maximum size and a specified queue length. When a task is submitted, if the number of
running threads is less than the core size, a new thread is created. Otherwise, if there is
room in the queue, the task is enqueued. Otherwise, if the number of running threads is
less than the maximum size, a new thread is created. Otherwise, the caller blocks until
room becomes available in the queue.
q ueuel ess-thread -po o l : Sometimes, a simple thread pool is required to run tasks in
separate threads, reusing threads as they complete their tasks with no intervening queue.
This type of pool is ideal for handling tasks which are long-running, perhaps utilizing
blocking I/O, since tasks are always started immediately upon acceptance rather than
accepting a task and then delaying its execution until other running tasks have
completed. This type of executor is declared using the q ueuel ess-thread -po o l executo r element.
bl o cki ng -q ueuel ess-thread -po o l : A thread pool executor with no queue where
threads submittings tasks may block. When a task is submitted, if the number of running
threads is less than the maximum size, a new thread is created. Otherwise, the caller
blocks until another thread completes its task and accepts the new one.
sched ul ed -thread -po o l :This is a special type of executor whose purpose is to
execute tasks at specific times and time intervals, based on the
java. uti l . co ncurrent. Sched ul ed T hread P o o l Executo r class. This type of
executor is configured with the sched ul ed -thread -po o l -executo r element:
In this example, we will use the unbo und ed -q ueue-thread -po o l to act as the executor.
Modify the values of max-threads and keepalive-time parameters to suit your server
needs.
<unbounded-queue-thread-pool name="uq-thread-pool">
<thread-factory name="http-connector-factory" />
<max-threads count="10" />
<keepalive-time time="30" unit="seconds" />
</unbounded-queue-thread-pool>
Or if you prefer to use the Management CLI:
339
[standalone@ localhost:9999 /] ./subsystem=threads/unbounded-queuethread-pool=uq-thread-pool:add(thread-factory="http-connectorfactory", keepalive-time={time=30, unit="seconds"}, max-threads=30)

3. Make t h e H T T P web co n n ect o r u se t h is t h read p o o l
In the same configuration file, locate the HTTP connector element under the web subsystem
and modify it to use the thread pool defined in the previous steps.
<connector name="http" protocol="HTTP/1.1" scheme="http" socketbinding="http" executor="uq-thread-pool" />
Again, if you prefer to use the Management CLI:
[standalone@ localhost:9999 /] ./subsystem=web/connector=http:writeattribute(name=executor, value="uq-thread-pool")
4. R est art t h e server
Restart the server (standalone or domain) so that the changes can take effect. Use the
following Management CLI commands to confirm if the changes from the steps above have
taken place:
[standalone@ localhost:9999 /] ./subsystem=threads:readresource(recursive=true)
{
"result" => {
"blocking-bounded-queue-thread-pool" => undefined,
"blocking-queueless-thread-pool" => undefined,
"bounded-queue-thread-pool" => undefined,
"queueless-thread-pool" => undefined,
"scheduled-thread-pool" => undefined,
"thread-factory" => {"http-connector-factory" => {
"group-name" => "uq-thread-pool",
"name" => "http-connector-factory",
"priority" => 9,
"thread-name-pattern" => "HTTP-%t"
}},
"unbounded-queue-thread-pool" => {"uq-thread-pool" => {
"keepalive-time" => {
"time" => 30L,
"unit" => "SECONDS"
},
"max-threads" => 30,
"name" => "uq-thread-pool",
"thread-factory" => "http-connector-factory"
}}
}
}
[standalone@ localhost:9999 /] ./subsystem=web/connector=http:readresource(recursive=true)
{
34 0
"result" => {
"enabled" => true,
"executor" => "uq-thread-pool",
"name" => "http",
"scheme" => "http",
"secure" => false,
"ssl" => undefined,
}
}
R esu lt
You have successfully created a thread factory and an executor and modified your HTTP Connector
to use this thread pool.
Report a bug
17.4 . Web Server Configurat ion

17.4 .1. About t he St andalone Apache HT T P Server
JBoss EAP 6 is tested and supported with the Apache HTTP server which is included with certified
versions of Red Hat Enterprise Linux 6. Apache HTTP server is also available for other operating
systems, such as Microsoft Windows Server. However, since Apache HTTP server is a separate
product produced by the Apache Foundation, it was previously difficult to be sure that the version of
Apache HTTP server a customer used was compatible with JBoss EAP.
A standalone Apache HTTP server bundle is now available as a separate download with JBoss EAP
6. This simplifies installation and configuration in environments other than Red Hat Enterprise Linux,
or on systems which already have a configured Apache HTTP server and want to use a separate
instance for web applications. You can download this Apache HTTP server as a separate download
in the Customer Service Portal, listed under the available JBoss EAP 6 downloads for your
installation platform.
Report a bug
17.4 .2. HT T PD Variable Convent ions

T ab le 17.4 . N at ive
Pro d u ct
H T T PD _C O N F
H T T PD _MO D U LES

HPUX
/etc/httpd/conf
/opt/hpws/apache/conf
/etc/httpd/modules
/opt/hpws/apache/modules
34 1
T ab le 17.5. EWS
Pro d u ct
H T T PD _C O N F
H T T PD _MO D U LES
/HTTPD _HOME/EWSROOT/httpd/conf
/HTTPD _HOME/EWSROOT/etc/httpd/conf
/HTTPD _HOME/EWSROOT/httpd/modules
/HTTPD _HOME/EWSROOT/lib/httpd/modules
Solaris
or
/HTTPD _HOME/EWSROOT/lib64/httpd/modules
Windows
/HTTPD _HOME/EWSROOT/etc/httpd/conf
/HTTPD _HOME/EWSROOT/lib/httpd/modules
or
/HTTPD _HOME/EWSROOT/lib64/httpd/modules
Report a bug
17.4 .3. Inst all Apache HT T P Server in Red Hat Ent erprise Linux 5, 6, and 7
(Zip)
Prereq u isit es
Root-level or administrator access.
A supported version of Java installed.
The following packages installed:
krb5-wo rkstati o n
mo d _auth_kerb (required for Kerberos functionality)
el i nks (required for the apachectl functionality)
apr-uti l -d evel (Apache Portability Runtime (APR))
apr-uti l -l d ap (Red Hat Enterprise Linux 7 only, required for LD AP authentication
functionality)
The Apache HT T P Server Z ip archive contains symbolic links to several Kerberos modules, which
is why the mo d _auth_kerb package is a prerequisite. If Kerberos functionality is not required, there
is no need to install the mo d _auth_kerb package and the associated symbolic link can be deleted:
EAP_HOME/httpd /mo d ul es/mo d _auth_kerb. so .
Pro ced u re 17.3. In st all t h e Ap ach e H T T P Server
1. N avig at e t o t h e JB o ss EAP d o wn lo ad s list f o r yo u r p lat f o rm, o n t h e R ed H at
C u st o mer Po rt al.
Log in to the Customer Portal and navigate to the So ftware D o wnl o ad s page. Select the
appropriate Pro d u ct and Versio n .
34 2
2. C h o o se t h e Ap ach e H T T P Server b in ary f ro m t h e list .

Find the Apache HT T P Server option for your operating system and architecture. Click the
D o wnl o ad link. A Z ip file containing the Apache HTTP Server distribution downloads to
your computer.
3. Ext ract t h e Z ip t o t h e syst em wh ere t h e Ap ach e H T T P Server b in ary will ru n .
Extract the Z ip file on your preferred server, to a temporary location. The Z ip file will contain
the httpd directory under a jboss-ews-version-number folder. Copy the httpd folder and
place it inside the EAP_HOME directory.
Your Apache HTTP Server is now located in the EAP_HOME/httpd / directory. This directory
is referred to as HTTPD_HOME.
4. R u n t h e Po st - in st allat io n scrip t an d creat e t h e apache u ser an d g ro u p acco u n t s
In a terminal emulator, navigate to the EAP _HO ME/httpd directory and execute the following
command with ro o t user privileges.
./.postinstall
Next, verify that the apache user exists on the system by running the following command:
id apache
If the user does not exist then it will need to be added, along with the appropriate usergroup.
In order to achieve this, execute the following with ro o t user privileges:
getent group apache >/dev/null || groupadd -g 48 -r apache
getent passwd apache >/dev/null || useradd -r -u 48 \
-g apache -s /sbin/nologin -d HTTPD_HOME/httpd/www -c "Apache"
apache
Once this is completed, if the apache user will be running the Apache HTTP Server service,
then the ownership of the HTTP directories will need to be changed to reflect this:
chown -R apache:apache httpd
To test that the above commands have been successful, check that the apache user has
execution permission to the Apache HTTP Server install path.
ls -l
The output should be similar to:
drwxrwxr-- 11 apache apache 4096 Feb 14 06:52 httpd
5. C o n f ig u re t h e Ap ach e H T T P Server.
Prior to starting the Apache HTTP Server, configure it to meet the needs of your organization.
You can use the documentation available from the Apache Foundation at
http://httpd.apache.org/ for general guidance.
34 3
6. St art t h e Ap ach e H T T P Server.

Start the Apache HTTP Server using the following command:
HTTPD_HOME/httpd/sbin/apachectl start
7. St o p t h e Ap ach e H T T P Server.
To stop the Apache HTTP Server, issue the following command:
HTTPD_HOME/httpd/sbin/apachectl stop
Report a bug
17.4 .4 . Inst all Apache HT T P Server in Red Hat Ent erprise Linux (RHEL) 5, 6,
and 7 (RPM)
Prereq u isit es
Root-level access.
The latest version of elinks package installed (required for the apachectl functionality).
Subscribe to Red Hat Enterprise Linux (RHEL) channels (to install Apache HTTP Server from
RHEL channels).
Subscribe to jbapppl atfo rm-6 -AR C H-server-VER S-rpm Red Hat Network (RHN) channel (to
install EAP specific distribution of Apache HTTP Server).
You can install Apache HTTP Server using either of the following methods:
From Red Hat Enterprise Linux (RHEL) channels: An active subscription to Red Hat Enterprise
Linux (RHEL) channels is necessary to install Apache HTTP server.
From jbapppl atfo rm-6 -AR C H-server-VER S-rpm channel (JBoss EAP specific distribution):
JBoss EAP distributes its own version of the Apache HTTP Server. An active subscription to
jbapppl atfo rm-6 -AR C H-server-VER S-rpm channel is necessary to install the JBoss EAP
specific distribution of Apache HTTP Server.
Pro ced u re 17.4 . In st all an d C o n f ig u re Ap ach e H T T P Server in R ed H at En t erp rise Lin u x
5 an d 6 ( R PM)
1. In st all httpd
To install the JBoss EAP specific version of httpd package run the following command:
yum install httpd
To install httpd explicitly from Red Hat Enterprise Linux (RHEL) channels run the following
command:
yum install httpd --disablerepo=jbappplatform-6-*
34 4
Note
You must run only one of the above commands to install the httpd package on your
system.
2. Set t h e Service B o o t B eh avio r

You can define the service behavior for the httpd service at boot from the command line or
with the service configuration graphical tool. Run the following command to define the
behavior:
chkconfig httpd on
To use the service configuration tool run the following command and change the service
setting in the displayed window:
system-config-services
3. St art httpd
Start httpd using the following command:
service httpd start
4. St o p httpd
Stop httpd using the following command:
service httpd stop
Pro ced u re 17.5. In st all an d C o n f ig u re Ap ach e H T T P Server in R ed H at En t erp rise Lin u x
7 ( R PM)
1. In st all httpd 22
To install the JBoss EAP specific version of httpd 22 package run the following command:
yum install httpd22
2. Set t h e Service B o o t B eh avio r
Run the following command to start the httpd 22 service at boot:
systemctl enable httpd22.service
3. St art httpd 22
Start httpd 22 using the following command:
systemctl start httpd22.service
34 5
4. St o p httpd 22
Stop httpd 22 using the following command:
systemctl stop httpd22.service
Report a bug
17.4 .5. Manage Apache HT T P Server Service for Microsoft Windows Server
Environment
Pro ced u re 17.6 . In st all t h e Ap ach e H T T P Server service f o r Micro so f t Win d o ws Server
en viro n men t
In st all t h e Ap ach e H T T P Server service u sin g t h is co mman d .
cd /D "%EWS_HOME%\bin"
httpd -k install
This command installs an Apache HTTP Server service named Apache2.2.
To specify a different name for the service, for example, ApacheBalancer, use the following
command.
httpd -k install -n ApacheBalancer
Pro ced u re 17.7. St art t h e Ap ach e H T T P Server service f o r Micro so f t Win d o ws Server
en viro n men t
T o st art a service, yo u can eit h er u se h t t p d .exe o r service man ag er.
Using httpd.exe:
httpd -k start -n Apache2.2
Using service manager:
net start Apache2.2
Pro ced u re 17.8. St o p t h e Ap ach e H T T P Server service f o r Micro so f t Win d o ws Server
en viro n men t
T o st o p a service, yo u can eit h er u se h t t p d .exe o r service man ag er.
Using httpd.exe:
httpd -k stop -n Apache2.2
Using service manager:
34 6
net stop Apache2.2

Pro ced u re 17.9 . U n in st all t h e Ap ach e H T T P Server service f o r Micro so f t Win d o ws Server
en viro n men t
T o u n in st all a service, it mu st b e ref eren ced b y n ame. Fo r examp le, t o u n in st all t h e
service n ames Ap ach eB alan cer, u se t h e f o llo win g co mman d .
httpd -k uninstall -n ApacheBalancer
Report a bug
17.4 .6. mod_clust er Configurat ion on Apache HT T P Server

Su mmary
The mod_cluster connector is an Apache HTTP Server-based load balancer. It uses a
communication channel to forward requests from the Apache HTTP Server to one of a set of
application server nodes. The following derivatives can be set to configure mod_cluster.
Note
There is no need to use ProxyPass directives because mod_cluster automatically configures
the URLs that must be forwarded to Apache HTTP Server.
T ab le 17.6 . mo d _clu st er D erivat ives

D erivat ive
D escrip t io n
Valu es
CreateBalancers
D efines how the balancers are

created in the Apache HTTP
Server VirtualHosts. This allows
directives like: P ro xyP ass
/bal ancer: //mycl uster1/.
0: Create all VirtualHosts

defined in Apache HTTP Server
1: D o not create balancers (at
least one ProxyPass or
ProxyMatch is required to
define the balancer names)
2: Create only the main server
D efault: 2
Wh ile u sin g t h e valu e 1, d o
n o t f o rg et t o co n f ig u re t h e
b alan cer in t h e Pro xyPass
d irect ive, b ecau se t h e
d ef au lt is an emp t y
st ickysessio n an d
no fai l o ver= O ff an d t h e
valu es received via t h e
MC MP C O N FIG messag e
are ig n o red .
34 7
D erivat ive
D escrip t io n
Valu es
UseAlias
Check that the alias

corresponds to the server
name.
0: Ignore aliases
1: Check aliases
D efault: 0
LBstatusRecalTime
WaitBeforeRemove
ProxyPassMatch/ProxyPass
Time interval in seconds for

loadbalancing logic to
recalculate the status of a
node.
Time in seconds before a
removed node is forgotten by
httpd.
ProxyPassMatch and
ProxyPass are mod_proxy
directives which, when using !
(instead of the back-end URL),
prevent reverse-proxy in the
path. This is used to allow
Apache HTTP Server to serve
static content. For example,
D efault: 5 seconds
D efault: 10 seconds
P ro xyP assMatch
^(/. *\. g i f)$ !
The above example allows the
Apache HTTP Server to serve
the . g i f files directly.
A hot-standby node in the mod_cluster logic is the last resort node to which all requests are routed if
all other nodes are down. This is similar to the hot-standby logic in mod_proxy.
To configure a hot-standby node, replace the dynamic-load-provider in mod_cluster subsystem with
a simple-load-provider with factor set to 0, for example:
<subsystem xmlns="urn:jboss:domain:modcluster:1.2">
<mod-cluster-config advertise-socket="modcluster" connector="ajp">
<dynamic-load-provider>
<load-metric type="busyness"/>
</dynamic-load-provider>
+
<simple-load-provider factor="0"/>
</mod-cluster-config>
</subsystem>
In mod_cluster-manager console, the node is displayed with OK status and Load: 0. For more
information, refer Apache mod_cluster-manager Application section in the JBoss Enterprise Application
Platform Development Guide.
For instance, if there are three nodes:
Node A, Load: 10
Node B, Load: 10
34 8
Node C, Load: 0
The load will be balanced between nodes A and B. If both the nodes are unavailable, node C will
take the load.
mo d _man ag er
The context of a mod_manager directive is VirtualHost in all cases, except when mentioned otherwise.
server co nfi g context implies that the directive must be outside a VirtualHost configuration. If not,
an error message is displayed and the Apache HTTP Server does not start.
T ab le 17.7. mo d _man ag er D erivat ives
D erivat ive
D escrip t io n
EnableMCPMReceive
Allow the VirtualHost to receive

the MCPM from the nodes.
Include EnableMCPMReceive in
the Apache HTTP Server
configuration to allow
mod_cluster to work. Save it in
the VirtualHost where you
configure advertising.
The base name for the names
$server_ro o t/l o g s/
that mod_manager uses to
store configuration, generate
keys for shared memory or
locked files. This must be an
absolute path name; the
directories are created if
needed. It is recommended that
these files are placed on a local
drive and not an NFS share.
MemManagerFile
Valu es
Context: server config

Maxcontext
Maxnode
Maxhost

contexts supported by
mod_cluster Context: server
config
The maximum number of nodes
supported by mod_cluster.
The maximum number of hosts
(aliases) supported by
mod_cluster. It also includes
the maximum number of
balancers. Context: server
config
D efault: 100
D efault: 20
D efault: 20
34 9
D erivat ive
D escrip t io n
Valu es
Maxsessionid
The number of active

sessi o ni d stored to provide
the number of active sessions
in the mod_cluster-manager
handler. A session is inactive
when mod_cluster does not
receive any information from
the session within 5 minutes.
0: the logic is not activated.

This field is for demonstration
and debugging purposes only.
MaxMCMPMaxMessSize
ManagerBalancerName
PersistSlots
CheckNonce
AllowD isplay
AllowCmd
ReduceD isplay
350
The maximum size of MCMP

messages from other Max
directives
The name of balancer to use
when the JBoss EAP instance
does not provide a balancer
name.
Tells mod_slotmem to persist
nodes, aliases and contexts in
files. Context: server config
Switch check of no nce when
using mod_cluster-manager
handler.
Calculated from other Max

directives. Min: 1024
Switch additional display on

mod_cluster-manager main
page.
on/off
Allow commands using

mod_cluster-manager URL.
on/off
Reduce the information

displayed on the main
mod_cluster-manager page, so
that more nodes can be
displayed on the page.
on/off
mycl uster
Off
on/off
D efault: on - No nce checked
D efault: off - only version is

displayed
D efault: on - Commands
allowed
D efault: off - full information is

displayed
D erivat ive
D escrip t io n
Valu es
SetHandler mod_clustermanager
D isplays information about the

node that mod_cluster sees
from the cluster. The
information includes generic
information and additionally
counts the number of active
sessions.
on/off
D efault: off
<Location
/mod_clustermanager>
SetHandler
mod_cluster-manager
Order
deny,allow
Allow from
127.0.0.1
</Location>
Note
When accessing the location defined in httpd . co nf:
Transferred: Corresponds to the POST data sent to the back-end server.
Connected: Corresponds to the number of requests that have been processed when the
mod_cluster status page was requested.
Num_sessions: Corresponds to the number of sessions mod_cluster report as active (on which
there was a request within the past 5 minutes). This field is not present when Maxsessionid is
zero and is for demonstration and debugging purposes only.
Report a bug
17.4 .7. Use an Ext ernal Web Server as t he Web Front -end for JBoss EAP 6
Applicat ions
O verview
For reasons to use an external web server as the web front-end, as well as advantages and
disadvantages of the different HTTP connectors supported by JBoss EAP 6, refer to Section 17.2.3,
Overview of HTTP Connectors . In some situations, you can use the Apache HTTP Server that
comes with your operating system. Otherwise, you can use the Apache HTTP Server that ships as
part of JBoss Enterprise Web Server.
After you have decided which web server and HTTP connector to use, refer to one of the following
procedures:
Section 17.4.3, Install Apache HTTP Server in Red Hat Enterprise Linux 5, 6, and 7 (Z ip)
351
Section 17.6.3, Install the mod_cluster Module Into Apache HTTP Server or JBoss Enterprise Web
Server (Z ip)
Section 17.7.3, Install the mod_jk Module Into the Apache HTTP Server (Z IP)
Section 17.9.3, Configure Microsoft IIS to Use the ISAPI Connector
Section 17.10.2, Configure the NSAPI Connector on Oracle Solaris
Section 17.4.8, Configure JBoss EAP 6 to Accept Requests From External Web Servers
Report a bug
17.4 .8. Configure JBoss EAP 6 t o Accept Request s From Ext ernal Web
Servers
O verview
JBoss EAP 6 does not need to know which proxy it is accepting requests from, only the port and
protocol to look for. This is not true of mo d _cl uster, which is more tightly coupled to the
configuration of JBoss EAP 6. But the following task works for mo d _jk, mo d _pro xy, ISAP I
co nnecto r, and NSAP I co nnecto r. Substitute the protocols and ports in the examples with the
ones you need to configure.
To configure JBoss EAP 6 for mo d _cl uster, refer to Section 17.6.6, Configure a mod_cluster
Worker Node .
Prereq u isit es
You need to be logged into the Management CLI or Management Console to perform this task. The
exact steps in the task use the Management CLI, but the same basic procedure is used in the
Management Console.
You need a list of which protocols you will be using, whether HTTP, HTTPS, or AJP.
Pro ced u re 17.10. Ed it C o n f ig u rat io n an d ad d So cket B in d in g s
1. C o n f ig u re t h e jvmR o ute syst em p ro p ert y.
For a standalone mode instance, remove the prefix /ho st= NODE_NAME. Replace
NO D E_NAME with the name of the host.
/ho st= NODE_NAME/system-pro perty= jvmR o ute/: ad d (val ue= NODE_NAME)
2. List t h e co n n ect o rs availab le in t h e web su b syst em.
Note
This step is only necessary if you are not using the ha or ful l -ha profiles for either a
standalone server, or a server group in a Managed D omain. Those configurations
already include all of the necessary connectors.
352
In order for an external web server to be able to connect to JBoss EAP 6's web server, the web
subsystem needs a connector. Each protocol needs its own connector, which is tied to a
socket group.
To list the connectors currently available, issue the following command:
/subsystem= web: read -chi l d ren-names(chi l d -type= co nnecto r)
If there is no line indicating the connector your need (HTTP, HTTPS, AJP), you need to add
the connector.
3. R ead t h e co n f ig u rat io n o f a co n n ect o r.
To see the details of how a connector is configured, you can read its configuration. The
following command reads the configuration of the AJP connector. The other connectors have
similar configuration output.
/subsystem= web/co nnecto r= ajp: read -reso urce(recursi ve= true)
{
"result" => {
"enabled" => true,
"protocol" => "AJP/1.3",
"scheme" => "http",
"secure" => false,
"socket-binding" => "ajp",
"ssl" => undefined,
}
}
4. Ad d t h e n ecessary co n n ect o rs t o t h e web su b syst em.
To add a connector to the web subsystem, it must have a socket binding. The socket binding
is added to the socket binding group used by your server or server group. The following
steps assume that your server group is server-g ro up-o ne and that your socket binding
group is stand ard -so ckets.
a. Ad d a so cket t o t h e so cket b in d in g g ro u p .
To add a socket to the socket binding group, issue the following command, replacing
the protocol and port with the ones you need.
/so cket-bi nd i ng -g ro up= stand ard -so ckets/so cketbi nd i ng = ajp: ad d (po rt= 80 0 9 )
b. Ad d t h e so cket b in d in g t o t h e web su b syst em.
Issue the following command to add a connector to the web subsystem, substituting
the socket binding name and protocol with the ones you need.
353
/subsystem= web/co nnecto r= ajp: ad d (so cket-bi nd i ng = ajp,

pro to co l = "AJP /1. 3", enabl ed = true, scheme= "http")
Report a bug
17.5. Clust ering

17.5.1. Use T CP Communicat ion for t he Clust ering Subsyst em
By default, cluster nodes monitor each other's status using the UD P protocol. Some networks only
allow TCP to be used. In this situation, you can add the T C P P ING protocol stack to your
configuration and use it as the default mechanism. These configuration options are available in the
command-line based Management CLI.
The mo d _cl uster subsystem also uses UD P communication by default, and you can choose to use
TCP here as well.
Refer to the following two procedures to configure JGroups and mod_cluster subsystems to use TCP
for network communication:
Section 17.5.2, Configure the JGroups Subsystem to Use TCP
Section 17.5.3, D isable Advertising for the mo d _cl uster Subsystem
Report a bug
17.5.2. Configure t he JGroups Subsyst em t o Use T CP

By default, the JGroups subsystem communicates using multicast UD P. Use the following procedure
to configure the JGroups subsystem to use unicast TCP instead.
To configure the mo d _cl uster subsystem to use TCP as well, see Section 17.5.3, D isable
Advertising for the mo d _cl uster Subsystem .
1. Mo d if y t h e f o llo win g scrip t t o su it yo u r en viro n men t .
Copy the following script into a text editor. If you use a different profile on a managed domain,
change the profile name. If you use a standalone server, remove the /pro fi l e= ful l -ha
portion of the commands. Modify the properties listed at the bottom of the command as
follows. Each of these properties is optional.
in it ial_h o st s
A comma-separated list of the hosts which are considered well-known, and will be
available to look up the initial membership.
p o rt _ran g e
If desired, you can assign a port range. If you assign a port range of 2, and the
initial port is 7600, then TCPPING will attempt to contact each host on ports 76007601. This property is optional.
t imeo u t
An optional timeout value, in milliseconds, for cluster members.
n u m_in it ial_memb ers
354
The number of nodes before the cluster is considered to be complete. This property
is optional.
batch
## If tcp is already added then you can remove it ##
/profile=full-ha/subsystem=jgroups/stack=tcp:remove
/profile=full-ha/subsystem=jgroups/stack=tcp:add(transport={"type"
=>"TCP", "socket-binding" => "jgroups-tcp"})
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=TCPPING)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=MERGE2)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=FD_SOCK,socket-binding=jgroups-tcp-fd)
/profile=full-ha/subsystem=jgroups/stack=tcp/:add-protocol(type=FD)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=VERIFY_SUSPECT)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=BARRIER)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=pbcast.NAKACK)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=UNICAST2)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=pbcast.STABLE)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=pbcast.GMS)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=UFC)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=MFC)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=FRAG2)
/profile=full-ha/subsystem=jgroups/stack=tcp/:addprotocol(type=RSVP)
/profile=full-ha/subsystem=jgroups:write-attribute(name=defaultstack,value=tcp)
run-batch
/profile=fullha/subsystem=jgroups/stack=tcp/protocol=TCPPING/property=initial_ho
sts/:add(value="HostA[7600],HostB[7600]")
/profile=fullha/subsystem=jgroups/stack=tcp/protocol=TCPPING/property=port_range
/:add(value=0)
/profile=fullha/subsystem=jgroups/stack=tcp/protocol=TCPPING/property=timeout/:a
dd(value=3000)
/profile=fullha/subsystem=jgroups/stack=tcp/protocol=TCPPING/property=num_initia
l_members/:add(value=3)
2. R u n t h e scrip t in b at ch mo d e.
355
Warning
The servers running the profile have to be shutdown before executing the batch file.
In a terminal emulator, navigate to the directory containing the jbo ss-cl i . sh script and
enter the command
./jboss-cli.sh -c --file=SCRIPT_NAME
where SCRIPT_NAME is the name and path containing the script.
R esu lt
The T C P P ING stack is now available to the JGroups subsystem. If it is used, the JGroups subsystem
uses TCP for all network communication. To configure the mo d _cl uster subsystem to use TCP as
well, see Section 17.5.3, D isable Advertising for the mo d _cl uster Subsystem .
Report a bug
17.5.3. Disable Advert ising for t he mo d _cl uster Subsyst em

By default, the mo d _cl uster subsystem's balancer uses multicast UD P to advertise its availability
to the background workers. If you wish, you can disable advertisement. Use the following procedure
to configure this behavior.
Pro ced u re 17.11.
1. Mo d if y t h e Ap ach e H T T P Server co n f ig u rat io n .
Modify the Apache HTTP Server configuration to disable server advertising and to use a
proxy list instead. The proxy list is configured on the worker, and contains all of the
mo d _cl uster-enabled Web servers to which the worker can talk.
The mo d _cl uster configuration for the Web server is located in HTTPD_HOME. See
Section 17.6.3, Install the mod_cluster Module Into Apache HTTP Server or JBoss Enterprise
Web Server (Z ip) and Section 17.6.5, Configure Server Advertisement Properties for Your
mod_cluster-enabled Web Server for more information about the file itself. Open the file
containing the virtual host which listens for MCPM requests (using the
Enabl eMC P MR ecei ve directive), and disable server advertising by changing the
ServerAd verti se directive as follows.
ServerAdvertise Off
2. D isab le ad vert isin g wit h in t h e mo d _cl uster su b syst em o f JB o ss EAP 6 , an d
p ro vid e a list o f p ro xies.
You can disable advertising for the mo d _cl uster subsystem and provide a list of proxies,
by using the web-based Management Console or the command-line Management CLI. The list
of proxies is necessary because the mo d _cl uster subsystem will not be able to
automatically discover proxies if advertising is disabled.
A. Man ag emen t C o n so le
356
If you use a managed domain, you can only configure mo d _cl uster in profiles where it
is enabled, such as the ha and ful l -ha profiles.
a. Log in to the Management Console and select the C o nfi g urati o n tab at the top
of the screen. If you use a managed domain, select either the ha or ful l -ha
profile from the P ro fi l e drop-down menu at the top left.
b. Expand the Subsystems menu then expand the Web menu and select
mo d _cl uster.
c. Click Ed i t under the Ad verti si ng tab under mo d _cl uster. To disable
advertising, clear the check box next to Ad verti se, and click Save.
Fig u re 17.1. mo d _cl uster Ad vert isin g C o n f ig u rat io n Screen

d. Click the P ro xi es tab. Click Ed i t and enter a list of proxy servers in the P ro xy
Li st field. The correct syntax is a comma-separated list of HO ST NAME: P O R T
strings, like the following:
10.33.144.3:6666,10.33.144.1:6666
Click the Save button to finish.
B. Man ag emen t C LI
The following two Management CLI commands create the same configuration as the
Management Console instructions above. They assume that you run a managed domain
and that your server group uses the ful l -ha profile. If you use a different profile, change
its name in the commands. If you use a standalone server using the stand al o ne-ha
357
profile, remove the /pro fi l e= ful l -ha portion of the commands.

/profile=full-ha/subsystem=modcluster/mod-clusterconfig=configuration/:write-attribute(name=advertise,value=false)
/profile=full-ha/subsystem=modcluster/mod-clusterconfig=configuration/:write-attribute(name=proxylist,value="10.33.144.3:6666,10.33.144.1:6666")
R esu lt
The Apache HTTP Server balancer no longer advertises its presence to worker nodes and UD P
multicast is no longer used.
Note
In order to set the attribute ad verti se= "fal se", you must also set the attribute pro xyl i st= "ad d ress: po rt". If the pro xy-l i st attribute is empty, the ad verti se= "fal se"
attribute is ignored. To disable the mod_cluster subsystem altogether, you may remove it from
the server configuration.
Report a bug
17.5.4 . Swit ch UDP t o T CP for Hornet Q Clust ering

The following example uses the default standalone-full-ha.xml file shipped with EAP 6.
Note
If security is enabled, you must set the cluster-password attribute:
<clusterpassword>${jboss.messaging.cluster.password:ChangeMe>}</clusterpassword>
1. R emo ve t h e b ro ad cast - g ro u p s an d d isco very- g ro u p s:

<broadcast-groups>
<broadcast-group name="bg-group1">
<socket-binding>messaging-group</socket-binding>
<broadcast-period>5000</broadcast-period>
<connector-ref>netty</connector-ref>
</broadcast-group>
</broadcast-groups>
<discovery-groups>
<discovery-group name="dg-group1">
358
<refresh-timeout>10000</refresh-timeout>
</discovery-group>
</discovery-groups
2. O p t io n ally, remo ve t h e "messag in g - g ro u p " so cket - b in d in g :
<socket-binding name="messaging-group" port="0" multicastaddress="${jboss.messaging.group.address:231.7.7.7}" multicastport="${jboss.messaging.group.port:9876}"/>
3. C o n f ig u re t h e ap p ro p riat e N et t y co n n ect o r( s) - o n e f o r each o f t h e o t h er n o d es
in t h e clu st er.
For example, if the cluster is 3 nodes then configure 2 Netty connectors, etc., if the cluster is 2
nodes then configure 1 Netty connector, etc. Here is a sample configuration for a 3-node
cluster:
<netty-connector name="other-cluster-node1" socket-binding="othercluster-node1"/>
<netty-connector name="other-cluster-node2" socket-binding="othercluster-node2"/>
4. C o n f ig u re t h e relat ed so cket b in d in g s.
Note
The system property substitution can be used for either " host" or " port" , if required.
<outbound-socket-binding name="other-cluster-node1">
<remote-destination host="otherNodeHostName1" port="5445"/>
<outbound-socket-binding name="other-cluster-node2">
<remote-destination host="otherNodeHostName2" port="5445"/>
5. C o n f ig u re t h e clu st er- co n n ect io n t o u se t h ese co n n ect o rs in st ead o f t h e
d isco very- g ro u p , wh ich is u sed b y d ef au lt :
<cluster-connection name="my-cluster">
<address>jms</address>
<static-connectors>
<connector-ref>other-cluster-node1</connector-ref>
<connector-ref>other-cluster-node2</connector-ref>
</static-connectors>
</cluster-connection>
This process has to be repeated on each of the cluster nodes so that each node has
connectors to every other node in the cluster.
359
Note
D o not configure a node with a connection to itself. This is considered as a
misconfiguration.
Report a bug
17.6. Web, HT T P Connect ors, and HT T P Clust ering

17.6.1. About t he mo d _cl uster HT T P Connect or
The mod_cluster module enables load balancing and is referred to as a connector. To learn about
other connectors, see one of the following:
Section 17.7.1, About the Apache mod_jk HTTP Connector
Section 17.9.1, About the Internet Server API (ISAPI)
Section 17.10.1, About the Netscape Server API (NSAPI)
The mod_cluster connector has several advantages over other connectors.
The mod_cluster Management Protocol (MCMP) is an additional connection between the JBoss
Enterprise Application Platform 6 servers and the Apache HTTP Server with the mod_cluster
module enabled. It is used by the JBoss Enterprise Application Platform servers to transmit serverside load balance factors and lifecycle events back to the Apache HTTP Server via a custom set
of HTTP methods.
D ynamic configuration of Apache HTTP Server with mod_cluster allows JBoss EAP 6 servers to
join the load balancing arrangement without manual configuration.
JBoss EAP 6 performs the load-balancing factor calculations, rather than relying on the Apache
HTTP Server with mod_cluster. This makes load balancing metrics more accurate than other
connectors.
The mod_cluster connector gives fine-grained application lifecycle control. Each JBoss EAP 6
server forwards web application context lifecycle events to the Apache HTTP Server, informing it to
start or stop routing requests for a given context. This prevents end users from seeing HTTP
errors due to unavailable resources.
AJP, HTTP or HTTPS transports can be used.
Report a bug
17.6.2. Configure t he mo d _cl uster Subsyst em

The mo d _cl uster subsystem can be configured via the Management Console and Management
CLI. In this topic the various configuration options are described, grouped as they appear in the
Management Console. Example Management CLI commands are provided for each option.
360
Note
The mo d _cl uster configuration page is only visible for ha and ful l -ha profiles. For a
managed domain these profiles are ha and ful l -ha, and for a standalone server they are
stand al o ne-ha and stand al o ne-ful l -ha.
Click the C o nfi g urati o n tab. If you are configuring a managed domain, select the correct profile
from the P ro fi l e drop-down list. Expand the Subsystems menu, then expand the Web menu and
select mo d _cl uster.
T ab le 17.8. mo d _cl uster Ad vert isin g C o n f ig u rat io n O p t io n s
O p t io n
D escrip t io n
Load Balancing Group
If this is not null, requests are

sent to a specific load
balancing group on the load
balancer. Leave this blank if
you do not want to use load
balancing groups. This is
unset by default.
Balancer
This attribute specifies what

mod_proxy balancer is to be
automatically configured by
mod_cluster on the Apache
HTTP Server. The default is
no ne, in which case the default
of mycl uster is used
(bal ancer: //mycl uster/
when expressed in mod_proxy
terms). This default value is
configured on the Apache
HTTP Server side with the
ManagerBalancerName
directive.
C LI C o mman d
/subsystem=modcluster
/mod-clusterconfig=configuration
/:writeattribute(name=loadbalancinggroup,value=myGroup)
/:writeattribute(name=balan
cer,value=myBalancer
)
If you use two different

bal ancer attribute values on
the JBoss EAP 6 worker
instances, there will be two
different mod_proxy balancers
created by mod_cluster
automatically on the Apache
HTTP Server.
361
O p t io n
D escrip t io n
Advertise Socket

to use for cluster advertising.
Advertise Security Key
Advertise
A string containing the security

key for advertising.
Whether or not advertising is

enabled. D efaults to true.
C LI C o mman d
/:writeattribute(name=adver
tisesocket,value=modclus
ter)
tise-securitykey,value=myKey)
tise,value=true)
T ab le 17.9 . mo d _cl uster Sessio n C o n f ig u rat io n O p t io n s

O p t io n
D escrip t io n
Sticky Session
Whether to use sticky sessions

for requests. This means that
after the client makes a
connection to a specific node,
further communication is routed
to that same node unless it
becomes unavailable. This
defaults to true, which is the
recommended setting.
Sticky Session Force
362
If true, a request is not

redirected to a new node if its
initial node becomes
unavailable but instead it fails.
This defaults to fal se.
C LI C o mman d
/:writeattribute(name=stick
ysession,value=true)
y-sessionforce,value=false)
O p t io n
D escrip t io n
Sticky Session Remove
Remove session information on

failover. This defaults to
fal se.
C LI C o mman d
y-sessionremove,value=false)
T ab le 17.10. mo d _cl uster Web C o n t ext C o n f ig u rat io n O p t io n s

O p t io n
D escrip t io n
Auto Enable Contexts
Whether to add new contexts to

mo d _cl uster by default or
not. This defaults to true. If
you change the default and
need to enable context
manually, the Web Application
can enable its context using the
enabl e() MBean method, or
via the mo d _cl uster
manager, which is a web
application which runs on the
httpd proxy on a named virtual
host or port which is specified
in that httpd's configuration.
A comma-separated list of
contexts that mo d _cl uster
should ignore. If no host is
indicated, the host is assumed
to be l o cal ho st. R O O T
indicates the root context of the
Web Application. The default
value is
R O O T ,i nvo ker,jbo ssws,ju
d d i ,co nso l e.
Excluded Contexts
C LI C o mman d
/:writeattribute(name=autoenablecontexts,value=true)
/:writeattribute(name=exclu
dedcontexts,value="ROOT
,invoker,jbossws,judd
i,console")
T ab le 17.11. mo d _cl uster Pro xy C o n f ig u rat io n O p t io n s

O p t io n
D escrip t io n
Proxy URL
If defined, this value will be

prepended to the URL of MCMP
commands.
C LI C o mman d
/:writeattribute(name=proxy
-url,value=myhost)
363
O p t io n
D escrip t io n
Proxy List
A comma-separated list of httpd

proxy addresses, in the format
ho stname: po rt. This
indicates the list of proxies that
the mo d _cl uster process will
attempt to communicate with
initially.
C LI C o mman d
/:writeattribute(name=proxy
list,value="127.0.0.1
,127.0.0.2")
C o n f ig u re SSL C o mmu n icat io n f o r mo d _cl uster

By default, mo d _cl uster communication happens over an unencrypted HTTP link. If you set the
connector scheme to HT T P S (refer to Table 17.9, mo d _cl uster Session Configuration Options ),
the settings below tell mo d _cl uster where to find the information to encrypt the connection.
T ab le 17.12. mo d _cl uster SSL C o n f ig u rat io n O p t io n s
O p t io n
D escrip t io n
Key Alias
The key alias, which was

chosen when the certificate was
created.
Password
This password is the keystore

password for both keystores:
certificate-key-file (Key File) and
ca-certificate-file (Cert File) and
the key/certificate entry
specified with Key Alias inside
Cert File.
Note
@ca-certificatepassword is the
truststore password and
value remains undefined
if you have not specified
it.
364
C LI C o mman d
/ssl=configuration/:
writeattribute(name=keyalias,value=jboss)
writeattribute(name=passw
ord,value=changeit)
O p t io n
D escrip t io n
CA Cert File/Trust Store
Trust store used to validate the

web server certificate.
Key Store
Cipher Suite
Revocation URL
Key store that holds the

certificate and private key that
identifies this instance.
The allowed encryption cipher

suite.
The URL of the Certificate

Authority revocation list.
C LI C o mman d
writeattribute(name=cacertificatefile,value=${user.ho
me}/jboss.crt)
writeattribute(name=certi
ficate-keyfile,value=${user.ho
me}/.keystore)
writeattribute(name=ciphe
r-suite,value=ALL)
writeattribute(name=carevocationurl,value=jboss.crl)
365
O p t io n
D escrip t io n
Protocol
The SSL protocols, which are

enabled.
C LI C o mman d
writeattribute(name=proto
col,value="TLSv1,
TLSv1.1,TLSv1.2")
You can also specify a

combination of protocols,
which is comma separated. For
example, TLSv1,
TLSv1.1,TLSv1.2.
Warning
Red Hat recommends
that you explicitly
disable SSL in favor of
TLSv1.1 or TLSv1.2 in all
affected packages.
C o n f ig u re mo d _cl uster N et wo rkin g O p t io n s

The available mo d _cl uster networking options control several different timeout behaviors for
different types of services with which the mo d _cl uster service communicates.
T ab le 17.13. mo d _cl uster N et wo rkin g C o n f ig u rat io n O p t io n s
O p t io n
D escrip t io n
Node Timeout
Timeout (in seconds) for proxy

connections to a worker. That
is the time mo d _cl uster will
wait for the back-end response
before returning error. That
corresponds to timeout in the
mod_proxy documentation. A
value of -1 indicates no
timeout. Note that
mo d _cl uster always uses a
cping/cpong before forwarding
a request and the
co nnecti o nti meo ut value
used by mo d _cl uster is the
ping value.
Number of milliseconds to wait
for a response from an httpd
proxy to MCMP commands
before timing out, and flagging
the proxy as in error.
Socket Timeout
366
C LI C o mman d
/:writeattribute(name=nodetimeout,value=-1)
/:writeattribute(name=socke
t-timeout,value=20)
O p t io n
D escrip t io n
Stop Context Timeout
The amount of time, measure in

units specified by
stopContextTimeoutUnit, for
which to wait for clean
shutdown of a context
(completion of pending
requests for a distributable
context; or
destruction/expiration of active
sessions for a nondistributable context).
Session D raining Strategy
Max Attempts
Flush Packets
Whether to drain sessions

before undeploying a web
application.
D EFAU LT
D rain sessions before
web application
undeploy only if the
web application is
non-distributable.
ALWAYS
Always drain
sessions before web
application undeploy,
even for distributable
web applications.
N EVER
D o not drain sessions
before web
application undeploy,
even for nondistributable web
application.
Number of times an httpd proxy
will attempt to send a given
request to a node before giving
up. The minimum value is 1,
meaning try only once. The
mo d _pro xy default is also 1,
which means that no retry
occurs.
Whether or not to enable packet
flushing to the Web server.
D efaults to fal se.
C LI C o mman d
/:writeattribute(name=stopcontexttimeout,value=10)
/:writeattribute(name=sessi
on-drainingstrategy,value=DEFAU
LT)
/:writeattribute(name=maxattempts,value=1)
/:writeattribute(name=flush
-packets,value=false)
367
O p t io n
D escrip t io n
Flush Wait
How long, in seconds, to wait

before flushing packets to the
Web server. D efaults to -1. A
value of -1 means to wait
forever before flushing packets.
Ping
SMAX
TTL

for a response to a ping from a
worker. D efaults to 10 seconds.
Soft maximum idle connection

count (the same as smax in
mod_proxy documentation).
The maximum value depends
on the httpd thread
configuration, and can be
either T hread sP erC hi l d or
1.
Time to live (in seconds) for idle

connections above smax,
default is 60
When no d eT i meo ut is not
defined the P ro xyT i meo ut
directive P ro xy is used. If
P ro xyT i meo ut is not defined
the server timeout T i meo ut is
used. This defaults to 300
seconds. no d eT i meo ut,
P ro xyT i meo ut, and
T i meo ut are set at the socket
level.
Node Timeout

for an available process from
the external Web server to
process a request. D efaults to 1, which means that
mod_cluster waits indefinitely
for the httpd worker to process
the request.
mo d _cl uster Lo ad Pro vid er C o n f ig u rat io n O p t io n s
368
C LI C o mman d
/:writeattribute(name=flush
-wait,value=-1)
/:writeattribute(name=ping,
value=10)
profile=fullha/subsystem=modclust
er/mod-clusterconfig=configuration
/:writeattribute(name=smax,
value=ThreadsPerChil
d)
/:writeattribute(name=ttl,v
alue=-1)
/:writeattribute(name=nodetimeout,value=-1)
The following mo d _cl uster configuration options are not available in the management console,
but can only be set using the Management CLI.
A simple load provider is used if no dynamic load provider is present. It assigns each cluster member
a load factor of 1, and distributes work evenly without applying a load balancing algorithm. To add
it, use the following Management CLI command.
[standalone@ localhost:9990 /] /subsystem=modcluster/mod-clusterconfig=configuration/:write-attribute(name=simple-load-provider, value=1)
A dynamic load provider can be configured to use a variety of algorithms in combination, in order to
determine which worker receives the next request. You can create a load provider and configure it to
suit your environment, and you can have more than one load metric active simultaneously by adding
them via the CLI. The default dynamic load provider uses busyness as the determining load metric.
The dynamic load provider options and possible load metrics are shown below.
T ab le 17.14 . mo d _cl uster D yn amic Lo ad Pro vid er O p t io n s
O p t io n
D escrip t io n
D ecay
The factor by which historical

metrics should decay in
significance.
History
The number of historic load

metric records to consider when
determining the load.
C LI C o mman d
/dynamic-loadprovider=configurati
on/:writeattribute(name=decay
,value=2)
on/:writeattribute(name=histo
ry,value=9)
369
O p t io n
D escrip t io n
Load Metric
The default load metric

included with the dynamic load
provider in JBoss EAP 6 is
busyness, which calculates
the load of the worker from the
amount of threads in the thread
pool being busy serving
requests. You can set the
capacity of this metric by which
the actual load is divided:
calculated_load / capacity. You
can set multiple load metrics
within the dynamic load
provider.
C LI C o mman d
on/loadmetric=busyness/:wri
teattribute(name=capac
ity,value=1.0)
teattribute(name=type,
value=busyness)
teattribute(name=weigh
t,value=1)
Lo ad Met ric Alg o rit h ms

cp u
The cpu load metric uses average CPU load to determine which node receives the next
work load.
mem
The mem load metric uses free native memory as a load metric. Usage of this metric is
discouraged because it provides a value that includes buffers and cache, so it is always a
very low figure on every decent system with good memory management.
h eap
The heap load metric uses the heap usage to determine which worker receives the next
370
The heap load metric uses the heap usage to determine which worker receives the next
work load.
sessio n s
The sessi o n load metric uses the number of active sessions as a metric.
req u est s
The req uests load metric uses the number of client requests to determine which worker
receives the next work load. For instance, capacity 1000 means that 1000 requests/sec is
considered to be a full load.
sen d - t raf f ic
The send -traffi c load metric uses the amount of traffic sent from the worker to the
clients. E.g. the default capacity of 512 indicates that the node should be considered under
full load if the average outbound traffic is 512 KB/s or higher.
receive- t raf f ic
The receive-traffic load metric uses the amount of traffic sent to the worker from the clients.
E.g. the default capacity of 1024 indicates that the worker should be considered under full
load if the average inbound traffic is 1024 KB/s or higher.
b u syn ess
This metric represents the amount of threads from the thread pool being busy serving
requests.
Examp le 17.2. Ad d a Lo ad Met ric

To add a load metric, use the ad d -metri c command.
/subsystem=modcluster/mod-cluster-config=configuration/:addmetric(type=sessions)
Examp le 17.3. Set a Valu e f o r an Exist in g Met ric

To set a value for an existing metric, use the wri te-attri bute command.
/subsystem=modcluster/mod-cluster-config=configuration/dynamic-loadprovider=configuration/load-metric=cpu/:writeattribute(name="weight",value="3")
Examp le 17.4 . C h an g e t h e Valu e o f an Exist in g Met ric

To change the value of an existing metric, use the wri te-attri bute command.
/subsystem=modcluster/mod-cluster-config=configuration/dynamic-loadprovider=configuration/load-metric=cpu/:writeattribute(name="type",value="busyness")
Examp le 17.5. R emo ve an Exist in g Met ric
371
To remove an existing metric, use the remo ve-metri c command.

/subsystem=modcluster/mod-cluster-config=configuration/:removemetric(type=sessions)
Report a bug
17.6.3. Inst all t he mod_clust er Module Int o Apache HT T P Server or JBoss

Ent erprise Web Server (Zip)
Prereq u isit es
To perform this task, you must be using Apache HTTP Server installed in Red Hat Enterprise Linux
6, or JBoss Enterprise Web Server, or the standalone Apache HTTP Server included as a
separate downloadable component of JBoss EAP 6.
If you need to install Apache HTTP Server in Red Hat Enterprise Linux 6, use the instructions from
the Red Hat Enterprise Linux 6 Deployment Guide.
If you need to install the standalone Apache HTTP Server included as a separate downloadable
component of JBoss EAP 6, refer to Section 17.4.3, Install Apache HTTP Server in Red Hat
Enterprise Linux 5, 6, and 7 (Z ip) .
If you need to install JBoss Enterprise Web Server, use the instructions from the JBoss Enterprise
Web Server Installation Guide.
D ownload the Webserver C o nnecter Nati ves package for your operating system and
architecture from the Red Hat Customer Portal at https://access.redhat.com. This package
contains the mod_cluster binary web server modules precompiled for your operating system. After
you extract the archive, the modules are located in the
EAP _HO ME/mo d ul es/system/l ayers/base/nati ve/l i b/httpd /mo d ul es directory.
The etc/ directory contains some example configuration files, and the share/ directory contains
some supplemental documentation.
You must be logged in with administrative (root) privileges.
Note
If you use a 64 bit system the mod_cluster binary web server modules will be located here:
EAP _HO ME/mo d ul es/system/l ayers/base/nati ve/l i b6 4 /httpd /mo d ul es. You
must use this path whenever you need access to the modules.
Pro ced u re 17.12. In st all t h e mo d _clu st er Mo d u le

1. D et ermin e yo u r Ap ach e H T T P Server co n f ig u rat io n lo cat io n .
Your Apache HTTP Server configuration location will be different depending on whether you
are using Red Hat Enterprise Linux's Apache HTTP Server, the standalone Apache HTTP
Server included as a separate downloadable component with JBoss EAP 6, or the Apache
HTTP Server available in JBoss Enterprise Web Server. It is one of the following three
options, and is referred to in the rest of this task as HTTPD_HOME.
372
Apache HTTP Server - /etc/httpd /

JBoss EAP 6 Apache HTTP Server - This location is chosen by you, based on the
requirements of your infrastructure.
JBoss Enterprise Web Server Apache HTTP Server - EWS_HOME/httpd /
2. C o p y t h e mo d u les t o t h e Ap ach e H T T P Server mo d u les d irect o ry.
Copy the four modules (the files ending in . so ) from the
EAP _HO ME/mo d ul es/system/l ayers/base/nati ve/l i b/httpd /mo d ul es directory of
the extracted Webserver Natives archive to the HTTPD_MODULES/ directory.
3. Fo r JB o ss En t erp rise Web Server, d isab le t h e mo d _pro xy_bal ancer mo d u le.
If you use JBoss Enterprise Web Server, the mo d _pro xy_bal ancer module is enabled by
default. It is incompatible with mod_cluster. To disable it, edit the HTTPD_CONF/httpd . co nf
and comment out the following line by placing a # (hash) symbol before the line which loads
the module. The line is shown without the comment and then with it, below.
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
# LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
Save and close the file.
4. C o n f ig u re t h e mo d _clu st er mo d u le.
The Webserver Natives archive contains a sample mo d _cl uster. co nf file
(EAP _HO ME/mo d ul es/system/l ayers/base/nati ve/etc/httpd /co nf). This file can
be used as a guide or copied and edited to create a HTTPD_CONF.D/JBoss_HTTP. co nf
file.
Note
Using the name JBoss_HTTP. co nf is an arbitrary convention in this document. The
configuration file will be loaded, regardless of its name, if it is saved in the co nf. d /
directory with the . co nf extension.
Add the following to your configuration file:
LoadModule
LoadModule
LoadModule
LoadModule
slotmem_module modules/mod_slotmem.so
manager_module modules/mod_manager.so
proxy_cluster_module modules/mod_proxy_cluster.so
advertise_module modules/mod_advertise.so
This causes Apache HTTP Server to automatically load the modules that mo d _cl uster
needs in order to function.
5. C reat e a p ro xy server list en er.
373
Continue editing HTTPD_CONF.D/JBo ss_HT T P . co nf and add the following minimal

configuration, replacing the values in capital letters with suitable values for your
environment.
Listen IP_ADDRESS:PORT
<VirtualHost IP_ADDRESS:PORT>
<Location />
Order deny,allow
Deny from all
Allow from *.MYDOMAIN.COM
</Location>
KeepAliveTimeout 60
MaxKeepAliveRequests 0
EnableMCPMReceive
ManagerBalancerName mycluster
ServerAdvertise On
</VirtualHost>
These directives create a new virtual server which listens on IP _AD D R ESS: P O R T , allows
connections from MY D O MAIN. C O M, and advertises itself as a balancer called mycl uster.
These directives are covered in detail in the documentation for Apache Web Server. To learn
more about the ServerAd verti se and Enabl eMC P MR ecei ve directives, and the
implications of server advertisement, see Section 17.6.5, Configure Server Advertisement
Properties for Your mod_cluster-enabled Web Server .
Save the file and exit.
6. R est art t h e Ap ach e H T T P Server.
The way to restart the Apache HTTP Server depends on whether you are using Red Hat
Enterprise Linux's Apache HTTP Server or the Apache HTTP Server included in JBoss
Enterprise Web Server. Choose one of the two methods below.
A. R ed H at En t erp rise Lin u x 6 Ap ach e H T T P Server
Issue the following command:
[root@ host]# servi ce httpd restart
B. JB o ss En t erp rise Web Server H T T P Server
JBoss Enterprise Web Server runs on both Red Hat Enterprise Linux and Microsoft
Windows Server. The method for restarting the Apache HTTP Server is different for each.
In Red Hat Enterprise Linux, JBoss Enterprise Web Server installs its Apache HTTP
Server as a service. To restart the Apache HTTP Server, issue the following two
commands:
[ro o t@ ho st ~ ]# servi ce httpd sto p
[ro o t@ ho st ~ ]# servi ce httpd start
374

Issue the following commands in a command prompt with administrative privileges:
C : \> net sto p httpd
C : \> net start httpd
R esu lt
The Apache HTTP Server is now configured as a load balancer, and can work with the
mo d _cl uster subsystem running JBoss EAP 6. To configure JBoss EAP 6 to be aware of
mod_cluster, see Section 17.6.6, Configure a mod_cluster Worker Node .
Report a bug
17.6.4 . Inst all t he mod_clust er Module Int o Apache HT T P Server or JBoss

Ent erprise Web Server (RPM)
Prereq u isit es
To perform this task, you must be using the Apache HTTP Server installed in Red Hat Enterprise
Linux 6, JBoss Enterprise Web Server, or the standalone Apache HTTP Server included as a
You must have an active subscription to the jbapppl atfo rm-6 -ARCH-server-VERS-rpm RHN
channel.
The RPM installation method is similar between Red Hat Enterprise Linux 5 and 6, only requiring
minor variations for Red Hat Enterprise Linux 6 users who have Apache HTTP Server 2.2.15
installed.
1. Install the mo d _cl uster-nati ve package using YUM:
yum install mod_cluster-native
2. Ap ach e H T T P Server:
If you choose to stay on Apache HTTP Server 2.2.15, you must disable the
mo d _pro xy_bal ancer module loaded by default by commmenting the Lo ad Mo d ul e
pro xy_bal ancer_mo d ul e line in the httpd.conf file.
Either edit the file manually or use the following command:
sed -i 's/^LoadModule proxy_balancer_module/#LoadModule
proxy_balancer_module/;s/$//' /etc/httpd/conf/httpd.conf
375
If you choose to upgrade to Apache HTTP Server 2.2.26, install the latest version using
the following command.
yum install httpd
3. To have the Apache HTTP Server service start at boot, enter the following command:
A. For Red Hat Enterprise Linux 5 and 6:
service httpd add
B. For Red Hat Enterprise Linux 7:
systemctl enable httpd22.service
4. Start the mod_cluster balancer with the following command:
A. For Red Hat Enterprise Linux 5 and 6:
service httpd start
B. For Red Hat Enterprise Linux 7:
Report a bug
17.6.5. Configure Server Advert isement Propert ies for Your mod_clust erenabled Web Server
Su mmary
For instructions on configuring your web server to interact with the mod_cluster load balancer, see
Server (Z ip) . One aspect of the configuration which needs more explanation is server advertisement.
When server advertisement is active, the web server broadcasts messages containing the IP address
and port number specified in the mod_cluster virtual host. To configure these values, see
Server (Z ip) . If UD P multicast is not available on your network, or you prefer to configure workers
with a static list of proxy servers, you can disable server advertisement and manually configure the
worker nodes. See Section 17.6.6, Configure a mod_cluster Worker Node for information on
configuring a worker.
The changes in this procedure need to be made to the httpd . co nf associated with your Apache
HTTP Server instance. This is often /etc/httpd /co nf/httpd . co nf in Red Hat Enterprise Linux,
or may be in the etc/ directory of your standalone Apache HTTP Server instance.
Pro ced u re 17.13. Ed it t h e h t t p d .co n f f ile an d imp lemen t t h e ch an g es
1. D isab le t h e Ad verti seFreq uency p aramet er, if it exist s.
376
If you have a line like the following in your <Vi rtual Ho st> statement, comment it out by
putting a # (hash) character before the first character. The value may be different from 5.
AdvertiseFrequency 5
2. Ad d t h e d irect ive t o d isab le server ad vert isemen t .
Add the following directive inside the <Vi rtual Ho st> statement, to disable server
advertisement.
ServerAdvertise Off
3. En ab le t h e ab ilit y t o receive MC PM messag es.
Add the following directive to allow the Web server to receive MCPM messages from the worker
nodes.
EnableMCPMReceive
4. R est art t h e Web server.
Restart the Web server by issuing one of the following, depending on whether you use Red
Hat Enterprise Linux or Microsoft Windows Server.
[root@ host ]# service httpd restart
net stop Apache2.2
net start Apache2.2
R esu lt
The web server no longer advertises the IP address and port of your mod_cluster proxy. To reiterate,
you need to configure your worker nodes to use a static address and port to communicate with the
proxy. See Section 17.6.6, Configure a mod_cluster Worker Node for more details.
Report a bug
17.6.6. Configure a mod_clust er Worker Node

Su mmary
A mod_cluster worker node consists of a JBoss EAP 6 server. This server can be part of a server
group in a Managed D omain, or a standalone server. A separate process runs within JBoss EAP 6,
which manages all of the worker nodes of the cluster. This is called the master. For more conceptual
information about nodes, see Section 17.2.4, Node types . For an overview of web server load
balancing, see to Section 17.2.3, Overview of HTTP Connectors .
377
Worker nodes in a managed domain share an identical configuration across a server group. Worker
nodes running as standalone servers are configured individually. The configuration steps are
otherwise identical.
Wo rker N o d e C o n f ig u rat io n
A standalone server must be started with the stand al o ne-ha or stand al o ne-ful l -ha profile.
A server group in a managed domain must use the ha or ful l -ha profile, and the ha-so ckets
or ful l -ha-so ckets socket binding group. JBoss EAP 6 ships with a cluster-enabled server
group called o ther-server-g ro up which meets these requirements.
Note
Where Management CLI commands are given, they assume you use a managed domain. If you
use a standalone server, remove the /pro fi l e= ful l -ha portion of the commands.
Pro ced u re 17.14 . C o n f ig u re a Wo rker N o d e

1. C o n f ig u re t h e n et wo rk in t erf aces.
By default, the network interfaces all default to 127. 0 . 0 . 1. Every physical host that hosts
either a standalone server or one or more servers in a server group needs its interfaces to be
configured to use its public IP address, which the other servers can see.
To change the IP address of a JBoss EAP 6 host, you need to shut it down and edit its
configuration file directly. This is because the Management API which drives the Management
Console and Management CLI relies on a stable management address.
Follow these steps to change the IP address on each server in your cluster to the master's
public IP address.
a. Start the JBoss EAP server using the profile described earlier in this topic.
b. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh command
in Linux or the EAP_HOME\bi n\jbo ss-cl i . bat command in Microsoft Windows
Server. Type co nnect to connect to the domain controller on the localhost, or
co nnect IP_ADDRESS to connect to a domain controller on a remote server.
c. Modify the external IP address for the manag ement, publ i c and unsecure
interfaces by typing the following commands. Be sure to replace
EXT ER NAL_IP _AD D R ESS in the command with the actual external IP address of the
host.
/i nterface= manag ement: wri te-attri bute(name= i netad d ress,val ue= "${jbo ss. bi nd . ad d ress. manag ement: EXTERNAL_IP_
ADDRESS}"
/i nterface= publ i c: wri te-attri bute(name= i netad d ress,val ue= "${jbo ss. bi nd . ad d ress. publ i c: EXTERNAL_IP_ADDR
ESS}"
/i nterface= unsecure: wri te-attri bute(name= i netad d ress,val ue= "${jbo ss. bi nd . ad d ress. unsecure: EXTERNAL_IP_AD
DRESS}"
rel o ad
378
You should see the following result for each command.

d. For hosts that participate in a managed domain but are not the master, you must
change the host name from master to a unique name. This name must be unique
across slaves and will be used for the slave to identify to the cluster, so make a note
of the name you use.
i. Start the JBoss EAP slave host using the following syntax:
bi n/d o mai n. sh --ho st-co nfi g = HOST_SLAVE_XML_FILE_NAME
For example:
ii. Launch the Management CLI.
iii. Use the following syntax to replace the host name:
/ho st= master: wri teattri bute(name= "name",val ue= UNIQUE_HOST_SLAVE_NAME)
For example:
/ho st= master: wri te-attri bute(name= "name",val ue= "ho stsl ave0 1")
This modifies the XML in the ho st-sl ave0 1. xml file as follows:
<host name="host-slave01" xmlns="urn:jboss:domain:1.6">
e. For newly configured hosts that need to join a managed domain, you must remove the
l o cal element and add the remo te element ho st attribute that points to the domain
controller. This step does not apply for a standalone server.
i. Start the JBoss EAP slave host using the following syntax:
bi n/d o mai n. sh --ho st-co nfi g = HOST_SLAVE_XML_FILE_NAME
For example:
ii. Launch the Management CLI.
iii. Use the following syntax specify the domain controller:
379
/ho st= UNIQ UE_HO ST _SLAVE_NAME/: wri te-remo te-d o mai nco ntro l l er(ho st= DOMAIN_CONTROLLER_IP_ADDRESS,po rt= ${jbo
ss. d o mai n. master. po rt: 9 9 9 9 },securi tyreal m= "Manag ementR eal m")
For example:
/ho st= ho st-sl ave0 1/: wri te-remo te-d o mai nco ntro l l er(ho st= "19 2. 16 8. 1. 20 0 ",po rt= ${jbo ss. d o mai n. m
aster. po rt: 9 9 9 9 },securi ty-real m= "Manag ementR eal m")
This modifies the XML in the ho st-sl ave0 1. xml file as follows:
<domain-controller>
<remote host="192.168.1.200"
port="${jboss.domain.master.port:9999}" securityrealm="ManagementRealm"/>
2. C o n f ig u re au t h en t icat io n f o r each slave server.
Each slave server needs a username and password created in the domain controller's or
standalone master's Manag ementR eal m. On the domain controller or standalone master,
run the EAP_HOME/bi n/ad d -user. sh command. Add a user with the same username as
the slave, to the Manag ementR eal m. When asked if this user will need to authenticate to an
external JBoss EAP 6 instance, answer yes. An example of the input and output of the
command is below, for a slave called sl ave1, with password chang eme.
user:bin user$ ./add-user.sh
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): a
Enter the details of the new user to add.
Realm (ManagementRealm) :
Username : sl ave1
Password : chang eme
Re-enter Password : chang eme
About to add user 'slave1' for realm 'ManagementRealm'
Is this correct yes/no? yes
Added user 'slave1' to file '/home/user/jboss-eap6.0/standalone/configuration/mgmt-users.properties'
Added user 'slave1' to file '/home/user/jboss-eap6.0/domain/configuration/mgmt-users.properties'
Is this new user going to be used for one AS process to connect to
380
another AS process e.g. slave domain controller?

yes/no? yes
To represent the user add the following to the server-identities
definition <secret value="Y2hhbmdlbWU=" />
3. C o p y t h e B ase6 4 - en co d ed <secret> elemen t f ro m t h e ad d -user. sh o u t p u t .
If you plan to specify the Base64-encoded password value for authentication, copy the
<secret> element value from the last line of the ad d -user. sh output as you will need it in
the step below.
4. Mo d if y t h e slave h o st ' s secu rit y realm t o u se t h e n ew au t h en t icat io n .
You can specify the secret value in one of the following ways:
A. Sp ecif y t h e B ase6 4 - en co d ed p asswo rd valu e in t h e server co n f ig u rat io n f ile
u sin g t h e Man ag emen t C LI.
a. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh
command in Linux or the EAP_HOME\bi n\jbo ss-cl i . bat command in
Microsoft Windows Server. Type co nnect to connect to the domain controller on
the localhost, or co nnect IP_ADDRESS to connect to a domain controller on a
remote server.
b. Specify the secret value by typing the following command. Be sure to replace the
SEC R ET _VALUE with the secret value returned from the ad d -user output from the
previous step.
/ho st= master/co re-servi ce= manag ement/securi tyreal m= Manag ementR eal m/serveri d enti ty= secret: ad d (val ue= "SECRET_VALUE")
B. C o n f ig u re t h e h o st t o g et t h e p asswo rd f ro m t h e vau lt .
a. Use the vaul t. sh script to generate a masked password. It will generate a string
like the following:
VAULT : : secret: : passwo rd : : O D VmY mJjNG MtZD U2ZC 0 0 Y mNl LWE4 O D MtZj
Q 1NWNmND U4 ZD c1T El O R V9 C UkVBS3Zhd Wx0 .
You can find more information on password vaults in the Security Architecture and
other JBoss EAP security documentation.
b. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh
Microsoft Windows Server. Type co nnect to connect to the domain controller on
the localhost, or co nnect IP_ADDRESS to connect to a domain controller on a
remote server.
c. Specify the secret value by typing the following command. Be sure to replace the
SEC R ET _VALUE with the masked password generated in the previous step.
381
/ho st= master/co re-servi ce= manag ement/securi tyreal m= Manag ementR eal m/serveri d enti ty= secret: ad d (val ue= "${VAULT : : secret: : passwo rd : : SEC
RET_VALUE}")
Note
When creating a password in the vault, it must be specified in plain text, not
Base64-encoded.
C. Sp ecif y t h e p asswo rd as a syst em p ro p ert y.

The following examples use server. i d enti ty. passwo rd as the system property name
for the password.
a. Specify the system property for the password in the server configuration file using
the Management CLI.
i. Launch the Management CLI, using the EAP_HOME/bi n/jbo ss-cl i . sh
Microsoft Windows Server. Type co nnect to connect to the domain
controller on the localhost, or co nnect IP_ADDRESS to connect to a
domain controller on a remote server.
ii. Type the following command to configure the secret identity to use the
system property.
/ho st= master/co re-servi ce= manag ement/securi tyreal m= Manag ementR eal m/serveri d enti ty= secret: ad d (val ue= "${server. i d enti ty. passwo r
d }")
You will see the following result for each command.
b. When you specify the password as a system property, you can configure the host
in either of the following ways:
A. Start the server entering the password in plain text as a command line
argument, for example:
-Dserver.identity.password=changeme
382
Note
The password must be entered in plain text and will be visible to anyone
who issues a ps -ef command.
B. Place the password in a properties file and pass the properties file URL as a
command line argument.
i. Add the key/value pair to a properties file. For example:
server.identity.password=changeme
ii. Start the server with the command line arguments
--properties=URL_TO_PROPERTIES_FILE
.
5. R est art t h e server.
The slave will now authenticate to the master using its host name as the username and the
encrypted string as its password.
R esu lt
Your standalone server, or servers within a server group of a managed domain, are now configured
as mod_cluster worker nodes. If you deploy a clustered application, its sessions are replicated to all
cluster nodes for failover, and it can accept requests from an external Web server or load balancer.
Each node of the cluster discovers the other nodes using automatic discovery, by default.To
configure automatic discovery, and the other specific settings of the mo d _cl uster subsystem, see
Section 17.6.2, Configure the mo d _cl uster Subsystem . To configure the Apache HTTP Server,see
Section 17.4.7, Use an External Web Server as the Web Front-end for JBoss EAP 6 Applications .
Report a bug
17.6.7. Migrat e T raffic bet ween Clust ers

Su mmary
After creating a new cluster using JBoss EAP 6, you can migrate traffic from the previous cluster to
the new one as part of an upgrade process. In this task, you will see the strategy that can be used to
migrate this traffic with minimal outage or downtime.
Prereq u isit es
A new cluster setup: Section 17.6.2, Configure the mo d _cl uster Subsystem (we will call this
cluster: ClusterNEW).
An old cluster setup that is being made redundant (we will call this cluster: ClusterOLD ).
Pro ced u re 17.15. U p g rad e Pro cess f o r C lu st ers - Lo ad B alan cin g G ro u p s
1. Setup your new cluster using the steps described in the prerequisites.
383
2. In both ClusterNEW and ClusterOLD , ensure that the configuration option sti cky-sessi o n
is set to true (this option is set to true by default). Enabling this option means that all new
requests made to a cluster node in any of the clusters will continue to go to the respective
cluster node.
/profile=full-ha/subsystem=modcluster/mod-clusterconfig=configuration/:write-attribute(name=stickysession,value=true)
3. Assuming that all the cluster nodes in ClusterOLD are members of ClusterOLD load
balancing group. One can set this configuration either via CLI or with an xml configuration
(either ha or full-ha profiles in domain mode and either standalone-ha or standalone-full-ha
in standalone mode):
/profile=full-ha/subsystem=modcluster/mod-clusterconfig=configuration/:write-attribute(name=load-balancinggroup,value=ClusterOLD)
<subsystem xmlns="urn:jboss:domain:modcluster:1.2">
<mod-cluster-config load-balancing-group="ClusterOLD"
advertise-socket="modcluster" connector="ajp">
<dynamic-load-provider>
<load-metric type="busyness"/>
</dynamic-load-provider>
</mod-cluster-config>
</subsystem>
4. Add the nodes in ClusterNEW to the mod_cluster configuration individually using the process
described here: Section 17.6.6, Configure a mod_cluster Worker Node . Additionally use the
aforementioned procedure and set their load balancing group to ClusterNEW.
At this point, one can see an output similar to the undermentioned shortened example on the
mod_cluster-manager console:
mod_cluster/<version>
LBGroup ClusterOLD: [Enable Nodes]
[Disable Nodes]
[Stop
Nodes]
Node node-1-jvmroute
(ajp://node1.oldcluster.example:8009):
[Enable Contexts]
[Disable Contexts]
[Stop Contexts]
Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets:
Off, ..., Load: 100
Virtual Host 1:
Contexts:
/my-deployed-application-context, Status:
ENABLED Request: 0 [Disable]
[Stop]
(ajp://node2.oldcluster.example:8009):
[Enable Contexts]
[Disable Contexts]
[Stop Contexts]
Balancer: qacluster, LBGroup: ClusterOLD, Flushpackets:
384
Off, ..., Load: 100

Virtual Host 1:
Contexts:
[Stop]
LBGroup ClusterNEW: [Enable Nodes]

[Disable Nodes]
[Stop
Nodes]
(ajp://node3.newcluster.example:8009):
[Enable Contexts]
[Disable Contexts]
[Stop Contexts]
Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets:
Off, ..., Load: 100
Virtual Host 1:
Contexts:
[Stop]
(ajp://node4.newcluster.example:8009):
[Enable Contexts]
[Disable Contexts]
[Stop Contexts]
Balancer: qacluster, LBGroup: ClusterNEW, Flushpackets:
Off, ..., Load: 100
Virtual Host 1:
Contexts:
[Stop]
5. There are old active sessions within the ClusterOLD group and any new sessions are created
either within the ClusterOLD or CLusterNEW group. Next, we want to disable the whole
ClusterOLD group, so as we can power down its cluster nodes without causing any error to
currently active client's sessions.
Click on the [D isable Nodes] link for LBGroup ClusterOLD on mod_cluster-manager web
console.
From this point on, only requests belonging to already established sessions will be routed to
members of ClusterOLD load balancing group. Any new client's sessions will be created in
the ClusterNEW group only. As soon as there are no active sessions within ClusterOLD
group, we can safely remove its members.
Note
Using [Stop Nodes] would command the load balancer to stop routing any requests to
this domain immediately. This will force a failover to another load balancing group
which will cause session data loss to clients, provided there is no session replication
between ClusterNEW and ClusterOLD .
D ef au lt Lo ad B alan cin g G ro u p
In case the current ClusterOLD setup does not contain any load balancing group settings (one can
see LBGroup:, on mod_cluster-manager console), one can still take advantage of disabling the
385
ClusterOLD nodes. In this case, click on [D isable Contexts] for each of the Cluster OLD nodes.
Contexts of these nodes will be disabled and once there are no active sessions present, they will be
ready for removal. New client's sessions will be created only on nodes with enabled contexts,
presumably Cluster NEW members in this example.
U sin g JB o ss EAP C LI
In addition to the possibility of using mod_cluster-manager web console, one can leverage CLI in
order to disable a particular context. The undermentioned operation is called stop-context, but it
makes the cluster node to send D ISABLE-APP command to the load balancer, having exactly the
same effect as clicking on [D isable] link next to a particular context on mod_cluster-manager console
(note that virtual host aliases, e.g. default-host were removed from the aforementioned mod_clustermanager console output example).
/profile=full-ha/subsystem=modcluster/:stop-context(context=/my-deployedapplication-context, virtualhost=default-host, waittime=50)
C o n clu sio n
To stop a particular context, cluster node or a whole load balancing group means to force the
balancer to stop routing any request to it immediately, thus forcing failover to another available
context. To disable a particular context, cluster node or a whole load balancing group means to tell
the balancer that no new sessions should be crated on this particular context/node/load balancing
group.
R esu lt
You have successfully upgraded a JBoss EAP 6 Cluster.
Report a bug
17.6.8. Configure fai l _o n_status Paramet er for mod_clust er

The fai l _o n_status parameter lists those HTTP status codes which, when returned by a worker
node in a cluster, will mark that node as having failed. The load balancer will then send future
requests to another worker node in the cluster. The failed worker node will remain in a NO T O K state
until it sends the load balancer a ST AT US message.
Note
The fai l _o n_status parameter cannot be used with HP-UX v11.3 hpws httpd B.2.2.15.15
from Hewlett-Packard as it does not support the feature.
The fai l _o n_status parameter must be configured in the httpd configuration file of your load
balancer. Multiple HTTP status codes for fai l _o n_status can be specified as a comma-separated
list. The following example specifies the HTTP status codes 20 3 and 20 4 for fai l _o n_status.
Examp le 17.6 . fai l _o n_status C o n f ig u rat io n
386
ProxyPass / balancer://MyBalancer stickysession=JSESSIONID|jsessionid

nofailover=on failonstatus=203,204
ProxyPassReverse / balancer://MyBalancer
ProxyPreserveHost on
Report a bug
17.7. Apache mod_jk

17.7.1. About t he Apache mod_jk HT T P Connect or
Apache mo d _jk is a HTTP connector which is provided for customers who need it for compatibility
purposes. It provides load balancing, and is a part of the natives package, R ed Hat JBo ss
Enterpri se Appl i cati o n P l atfo rm 6 . X. 0 Webserver C o nnecto r Nati ves (zip
installation) which is available on the Red Hat Customer Portal at https://access.redhat.com. mo d _jk
can be installed from the RPMs. For details of installing from RPM, refer Section 17.7.4, Install the
mod_jk Module Into the Apache HTTP Server (RPM) . For supported platforms, see
https://access.redhat.com/articles/111663. The mo d _jk connector is maintained by Apache, and its
documentation is located at http://tomcat.apache.org/connectors-doc/.
JBoss EAP 6 can accept workloads from an Apache HTTP proxy server. The proxy server accepts
client requests from the web front-end, and passes the work to participating JBoss EAP 6 servers. If
sticky sessions are enabled, the same client request always goes to the same JBoss EAP 6 server,
unless the server is unavailable.
Unlike the JBoss mo d _cl uster HTTP connector, an Apache mo d _jk HTTP connector does not
know the status of deployments on servers or server groups, and cannot adapt where it sends its
work accordingly.
mo d _jk communicates over the AJP 1.3 protocol. mo d _cl uster supports other protocols. For more
information, refer Table HTTP connector features and constraints in Section 17.2.3, Overview of
HTTP Connectors .
Note
mo d _cl uster is a more advanced load balancer than mo d _jk. mo d _cl uster provides all
of the functionality of mo d _jk and additional features. For more information about
mo d _cl uster, see Section 17.6.1, About the mo d _cl uster HTTP Connector .
N ext st ep : C o n f ig u re a JB o ss EAP 6 in st an ce t o p art icip at e in a mo d _jk lo ad b alan cin g

g ro u p
Section 17.7.3, Install the mod_jk Module Into the Apache HTTP Server (Z IP)
Report a bug
17.7.2. Configure JBoss EAP 6 t o Communicat e wit h Apache mod_jk

O verview
387
The mod_jk HTTP connector has a single component, the mo d _jk. so module loaded by the web
server. This module receives client requests and forwards them to the container, in this case JBoss
EAP 6. JBoss EAP 6 must also be configured to accept these requests and send replies back to the
web server.
Configuring the Apache HTTP Server is covered in Section 17.7.3, Install the mod_jk Module Into the
Apache HTTP Server (Z IP) .
In order for JBoss EAP 6 to be able to communicate with the Apache HTTP server, it must have the
AJP/1.3 connector enabled. This connector is present by default in the following configurations:
In a managed domain, in server groups using the ha and ful l -ha profiles, and the ha or ful l ha socket binding group. The o ther-server-g ro up server group is configured correctly in a
default installation.
In a standalone server, the stand al o ne-ha and stand al o ne-ful l -ha profiles are
configured for clustered configurations. To start the standalone server with one of these profiles,
issue the following command, from the EAP_HOME/ directory. Substitute the appropriate profile
name.
EAP_HOME/bi n/stand al o ne. sh --server-co nfi g = stand al o ne-ha. xml
For Windows, enter the following command:
EAP_HOME\bi n\stand al o ne. bat --server-co nfi g = stand al o ne-ha. xml
Report a bug
17.7.3. Inst all t he mod_jk Module Int o t he Apache HT T P Server (ZIP)

Prereq u isit es
To perform this task, you must be using Apache HTTP Server installed on a supported
environment or the Apache HTTP Server installed from JBoss Enterprise Web Server. Note that the
JBoss Enterprise Web Server is part of the JBoss EAP 6 distribution.
If you need to install the Red Hat Enterprise Linux native Apache HTTP Server, use the
instructions in the Red Hat Enterprise Linux Deployment Guide.
If you need to install the HP-UX native Apache HTTP Server, use the instructions in the HP-UX Web
Server Suite Installation Guide, available at
https://h20392.www2.hp.com/portal/swdepot/displayInstallInfo.do?
productNumber=HPUXWSATW232.
If you need to install JBoss Enterprise Web Server, use the instructions in the JBoss Enterprise Web
Server Installation Guide.
If you are using Apache HTTP Server, download the JBoss EAP 6 Native Components package
for your platform from the Red Hat Customer Portal at https://access.redhat.com. This package
contains both the mo d _jk and mo d _cl uster precompiled binaries. If you are using JBoss
Enterprise Web Server, it already includes the binary for mo d _jk.
If you are using Red Hat Enterprise Linux (RHEL) 5 and native Apache HTTP server (httpd 2.2.3),
load the mod_perl module prior to loading mod_jk module.
388
To view the HTTPD variable conventions, see Section 17.4.2, HTTPD Variable Conventions
Pro ced u re 17.16 . In st all t h e mo d _jk Mo d u le
1. C o n f ig u re t h e mo d _jk mo d u le.
a. Create a new file called HTTPD_HOME/co nf. d /mo d -jk. co nf and add the
following to it:
Note
The JkMo unt directive specifies which URLs Apache HTTP Server must
forward to the mod_jk module. Based on the directive's configuration, mod_jk
sends the received URL to the correct workers.
To serve static content directly, and only use the load balancer for Java
applications, the URL path must be /appl i cati o n/*. To use mod_jk as a
load balancer, use the value /*, to forward all URLs to mod_jk.
# Load mod_jk module

# Specify the filename of the mod_jk lib
LoadModule jk_module modules/mod_jk.so
# Where to find workers.properties
JkWorkersFile conf/workers.properties
# Where to put jk logs
JkLogFile logs/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel info
# Select the log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y]"
# JkOptions indicates to send SSK KEY SIZE
JkOptions +ForwardKeySize -ForwardDirectories
# JkRequestLogFormat
JkRequestLogFormat "%w %V %T"
# Mount your applications
# The default setting only sends Java application data to
mod_jk.
# Use the commented-out line to send all URLs through mod_jk.
# JkMount /* loadbalancer
JkMount /application/* loadbalancer
# Add shared memory.
# This directive is present with 1.2.10 and
# later versions of mod_jk, and is needed for
# for load balancing to work properly
JkShmFile logs/jk.shm
389
# Add jkstatus for managing runtime data

<Location /jkstatus/>
JkMount status
Order deny,allow
Deny from all
Allow from 127.0.0.1
</Location>
Look over the values and ensure they are reasonable for your setup. When you are
satisfied, save the file.
b. Sp ecif y a JK Mo u n t File d irect ive
In addition to the JKMount directive in the mo d -jk. co nf, you can specify a file
which contains multiple URL patterns to be forwarded to mod_jk.
i. Add the following to the HTTPD_HOME/co nf/mo d -jk. co nf file:
# You can use external file for mount points.
# It will be checked for updates each 60 seconds.
# The format of the file is: /url=worker
# /examples/*=loadbalancer
JkMountFile conf/uriworkermap.properties
ii. Create a new file called HTTPD_CONF/uri wo rkermap. pro perti es, with a
line for each URL pattern to be matched. The following example shows
examples of the syntax of the file.
# Simple worker configuration file
/*=loadbalancer
c. C o p y t h e mo d _jk.so f ile t o t h e h t t p d ' s mo d u les d irect o ry
Note
This is only necessary if the Apache HTTP server does not have mo d _jk. so
in its mo d ul es/ directory. You can skip this step if you are using the Apache
HTTP server included as a download as part of JBoss EAP 6.
Extract the Native Web Server Connectors Z ip package. Locate the mo d _jk. so file in
either the
EAP_HOME/mo d ul es/system/l ayers/base/nati ve/l i b/httpd /mo d ul es/ or
the
EAP_HOME/mo d ul es/system/l ayers/base/nati ve/l i b6 4 /httpd /mo d ul es/
directories, depending on whether your operating system is 32-bit or 64-bit.
Copy the file to the HTTPD_MODULES/ directory.
2. C o n f ig u re t h e mo d _jk wo rker n o d es.
390
a. Create a new file called HTTPD_CONF/wo rkers. pro perti es. Use the following
example as your starting point, and modify the file to suit your needs.
# Define list of workers that will be used
# for mapping requests
worker.list=loadbalancer,status
# Define Node1
# modify the host as your host IP or DNS name.
worker.node1.port=8009
worker.node1.host=node1.mydomain.com
worker.node1.type=ajp13
worker.node1.ping_mode=A
worker.node1.lbfactor=1
# Define Node2
# modify the host as your host IP or DNS name.
worker.node2.port=8009
worker.node2.host=node2.mydomain.com
worker.node2.type=ajp13
# Load-balancing behavior
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=node1,node2
worker.loadbalancer.sticky_session=1
# Status worker for managing load balancer
worker.status.type=status
For a detailed description of the syntax of the wo rkers. pro perti es file, and
advanced configuration options, see Section 17.7.5, Configuration Reference for
Apache mod_jk Workers .
3. R est art t h e Web Server.
The way to restart the web server depends on whether you are using Red Hat Enterprise
Linux's Apache HTTP server or the Apache HTTP server included in JBoss Enterprise Web
Server. Choose one of the following methods.
A. R ed H at En t erp rise Lin u x' s Ap ach e H T T P Server
Issue the following command:
[root@ host]# servi ce httpd restart
B. JB o ss En t erp rise Web Server Ap ach e H T T P Server
JBoss Enterprise Web Server runs on both Red Hat Enterprise Linux and Microsoft
Windows Server. The method for restarting the web server is different for each.
A. R ed H at En t erp rise Lin u x, in st alled f ro m R PM
In Red Hat Enterprise Linux, JBoss Enterprise Web Server installs its web server as a
service. To restart the web server, issue the following two commands:
391
[root@ host ~]# service httpd stop

[root@ host ~]# service httpd start
B. R ed H at En t erp rise Lin u x, in st alled f ro m Z ip
If you have installed the JBoss Enterprise Web Server Apache HTTP server from a Z ip
archive, use the apachectl command to restart the web server. Replace EWS_HOME
with the directory where you unzipped JBoss Enterprise Web Server Apache HTTP
server.
[root@ host ~]# EWS_HOME/httpd/sbin/apachectl restart
C. Micro so f t Win d o ws Server
Issue the following commands in a command prompt with administrative privileges:
net stop Apache2.2
net start Apache2.2
D . So laris
Issue the following commands in a command prompt with administrative privileges.
Replace EWS_HOME with the directory where you unzipped JBoss Enterprise Web
Server Apache HTTP server.
[root@ host ~] EWS_HOME/httpd/sbin/apachectl restart
R esu lt
The Apache HTTP server is now configured to use the mod_jk load balancer. To configure JBoss
EAP 6 to be aware of mod_jk, see Section 17.4.8, Configure JBoss EAP 6 to Accept Requests From
External Web Servers .
Report a bug
17.7.4 . Inst all t he mod_jk Module Int o t he Apache HT T P Server (RPM)

Prereq u isit es
To perform this task, you must be using the Apache HTTP Server installed in Red Hat Enterprise
Linux 6, JBoss Enterprise Web Server, or the standalone Apache HTTP Server included as a
You must have an active subscription to the jbapppl atfo rm-6 -AR C HIT EC T UR E-serverR HEL_VER SIO N-rpm channel.
392

Pro ced u re 17.17. R ed H at En t erp rise Lin u x 5: mo d _jk wit h Ap ach e H T T P Server 2.2.3
1. Install mod_jk-ap22 1.2.37 and its dependency mod_perl from the jbapppl atfo rm-6 AR C HIT EC T UR E-server-5-rpm channel:
yum install mod_jk
2. O p t io n al: Copy the sample configuration files for use:
cp /usr/share/doc/mod_jk-ap22-1.2.37/mod_jk.conf.sample
/etc/httpd/conf.d/mod_jk.conf
cp /usr/share/doc/mod_jk-ap22-1.2.37/workers.properties.sample
/etc/httpd/conf/workers.properties
These files should be edited to suit your needs.
3. Start the server:
service httpd start
Note
The following error message indicates that your mod_jk module had been loaded before
mod_perl was present:
Cannot load /etc/httpd/modules/mod_jk.so into server:
/etc/httpd/modules/mod_jk.so: undefined symbol:
ap_get_server_description
To ensure mod_perl module is loaded before mod_jk module add the following to the
/etc/httpd /co nf. d /mo d _jk. co nf:
<IfModule !perl_module>
LoadModule perl_module modules/mod_perl.so
</IfModule>
LoadModule jk_module modules/mod_jk.so
Pro ced u re 17.18. R ed H at En t erp rise Lin u x 5: mo d _jk wit h JB o ss EAP Ap ach e H T T P
Server 2.2.26
1. Install both mod_jk and the latest Apache HTTP Server 2.2.26 provided by the
jbapppl atfo rm-6 -AR C HIT EC T UR E-server-5-rpm channel with this command:
yum install mod_jk httpd
393

service httpd start
Pro ced u re 17.19 . R ed H at En t erp rise Lin u x 6 : mo d _jk wit h JB o ss EAP Ap ach e H T T P
Server 2.2.26
1. Install mod_jk-ap22 1.2.37 and Apache HTTP Server 2.2.26 httpd package from the
jbapppl atfo rm-6 -AR C HIT EC T UR E-server-6 -rpm channel (any existing versions will
be updated):
yum install mod_jk httpd
service httpd start
Pro ced u re 17.20. R ed H at En t erp rise Lin u x 6 : mo d _jk wit h Ap ach e H T T P Server 2.2.15
1. Install mod_jk with Apache HTTP Server 2.2.15 with the following command:
yum install mod_jk
394

service httpd start
Pro ced u re 17.21. R ed H at En t erp rise Lin u x 7: mo d _jk wit h JB o ss EAP Ap ach e H T T P
Server 2.2.26
1. Install mod_jk-ap22 1.2.37 and Apache HTTP Server 2.2.26 httpd22 package from the
jbapppl atfo rm-6 -AR C HIT EC T UR E-server-6 -rpm channel (any existing versions will
be updated):
yum install mod_jk
/etc/httpd22/conf.d/mod_jk.conf
/etc/httpd22/conf/workers.properties
Report a bug
17.7.5. Configurat ion Reference for Apache mod_jk Workers

The wo rkers. pro perti es file defines the behavior of the workers which mod_jk passes client
requests to. In Red Hat Enterprise Linux, the file resides in
/etc/httpd /co nf/wo rkers. pro perti es. The wo rkers. pro perti es file defines where the
different application servers are located, and the way the work load should be balanced across them.
The configuration is divided into three sections. The first section deals with global properties, which
apply to all workers. The second section contains settings which apply to a specific Load Balancer.
The third section contains settings which apply to a specific worker node balanced by the Load
Balancer.
The general structure of a property is wo rker. WORKER_NAME. DIRECTIVE, where WORKER_NAME
is a unique name for the worker, and DIRECTIVE is the setting to be applied to the worker.
C o n f ig u rat io n ref eren ce f o r Ap ach e mo d _jk Lo ad B alan cers
Templates specify default per-Load Balancer settings. You can override the template within the Load
Balancer settings itself. You can see an example of Load Balancer templates in Example 17.7,
Example wo rkers. pro perti es file .
T ab le 17.15. G lo b al p ro p ert ies
395
Pro p ert y
D escrip t io n
worker.list
The list of Load Balancers names used by mod_jk. These Load Balancers
are available to receive requests.
T ab le 17.16 . Man d at o ry D irect ives

Pro p ert y
D escrip t io n
type
The type of the Load Balancer. The default type is ajp13. Other possible
values are ajp14 , l b, status.
For more information on these directives, refer to the Apache Tomcat
Connector AJP Protocol Reference at
http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html.
T ab le 17.17. Lo ad B alan cin g D irect ives

Pro p ert y
D escrip t io n
balance_workers
Specifies the worker nodes that the load balancer must manage. You can
use the directive multiple times for the same load balancer. It consists of a
comma-separated list of worker node names. This is set per Load
Balancer, not per worker node.
Specifies whether requests from the same session are always routed to
the same worker. The default is 1, meaning that sticky sessions are
enabled. To disable sticky sessions, set it to 0 . Sticky sessions should
usually be enabled, unless all of your requests are truly stateless. This is
set per Load Balancer, not per worker node.
sticky_session
T ab le 17.18. C o n n ect io n D irect ives

Pro p ert y
D escrip t io n
host
The hostname or IP address of the Load Balancer. The Load Balancer

must support the ajp protocol stack. The default value is l o cal ho st.
The port number of the remote server instance listening for defined
protocol requests. The default value is 80 0 9 , which is the default
listening port for AJP13 Load Balancers. The default value for AJP14
Load Balancers is 80 11.
port
396
Pro p ert y
D escrip t io n
ping_mode
The conditions under which connections are probed for network status.
The probe uses an empty AJP13 packet for CPing, and expects a CPong
in response. Specify the conditions by using a combination of directive
flags. The flags are not separated by a comma or any white-space. The
ping_mode can be any combination of C , P , I, and A.
C - Connect. Probe the connection one time after connecting to the
server. Specify the timeout using the value of co nnect_ti meo ut.
Otherwise, the value of pi ng _ti meo ut is used.
P - Prepost. Probe the connection before sending each request to the
server. Specify the timeout using the prepo st_ti meo ut directive.
Otherwise, the value of pi ng _ti meo ut is used.
I - Interval. Probe the connection at an interval specified by
co nnecti o n_pi ng _i nterval , if present. Otherwise, the value of
pi ng _ti meo ut is used.
A - All. A shortcut for C P I, which specifies that all connection probes
are used.
ping_timeout,
connect_timeout,
prepost_timeout,
connection_ping_inter
val
lbfactor
The timeout values for the connection probe settings above. The value is
specified in milliseconds, and the default value for pi ng _ti meo ut is
10000.
Specifies the load-balancing factor for an individual Load Balancer, and

only applies to a member worker node of a load balancer. This is useful
to give a more powerful server more of the work load. To give a worker 3
times the default load, set this to 3: wo rker. my_wo rker. l bfacto r= 3
Examp le 17.7. Examp le wo rkers. pro perti es f ile

worker.balancer1.type=lb
worker.balancer2.type=lb
worker.balancer1.sticky_sessions=1
worker.balancer1.balance_workers=node1
worker.balancer2.sticky_session=1
worker.balancer2.balance_workers=node2,node3
worker.nodetemplate.type=ajp13
worker.nodetemplate.port=8009
worker.node1.template=nodetemplate
worker.node1.host=localhost
worker.node1.ping_mode=CI
worker.node1.connection_ping_interval=9000
worker.node2.host=192.168.1.1
worker.node3.host=192.168.1.2
397
The example above demonstrates the use of multiple Load Balancers to serve the content on behalf
of a web server. The reasons for such configuration can be:
To have different contexts to be served by different Load Balancers, providing a development
environment in which all the developers share the same web server but own a Load Balancer of
their own.
To have different virtual hosts served by different processes, providing a clear separation between
sites belonging to different companies.
To provide load balancing, that is, run multiple Load Balancers each on its own machine and
divide the requests between them.
Further configuration details for Apache mod_jk are out of the scope of this document. Refer to the
Apache documentation at http://tomcat.apache.org/connectors-doc/ for further instructions.
Report a bug
17.8. Apache mod_proxy

17.8.1. About t he Apache mod_proxy HT T P Connect or
Apache provides two different proxying and load balancing modules for its httpd: mo d _pro xy and
mo d _jk. To learn more about mo d _jk, refer to Section 17.7.1, About the Apache mod_jk HTTP
Connector . JBoss EAP 6 supports use of either of these, although mo d _cl uster, the JBoss HTTP
connector, more closely couples JBoss EAP 6 and the external httpd, and is the recommended HTTP
connector. Refer to Section 17.2.3, Overview of HTTP Connectors for an overview of all supported
HTTP connectors, including advantages and disadvantages.
Unlike mo d _jk, mo d _pro xy supports connections over HTTP and HTTPS protocols. Each of them
also support the AJP protocol.
mo d _pro xy can be configured in standalone or load-balanced configurations, and it supports the
notion of sticky sessions.
The mo d _pro xy module requires JBoss EAP 6 to have the HTTP, HTTPS or AJP web connector
configured. This is part of the Web subsystem. Refer to Section 15.1, Configure the Web Subsystem
for information on configuring the Web subsystem.
Note
mo d _cl uster is a more advanced load balancer than mo d _pro xy. mo d _cl uster provides
all of the functionality of mo d _pro xy and additional features. For more information about
mo d _cl uster, see Section 17.6.1, About the mo d _cl uster HTTP Connector .
Report a bug
17.8.2. Inst all t he mod_proxy HT T P Connect or int o Apache HT T P Server

O verview
mo d _pro xy is a load-balancing module provided by Apache. This task presents a basic
configuration. For more advanced configuration, or additional details, see Apache's mo d _pro xy
documentation at https://httpd.apache.org/docs/2.2/mod/mod_proxy.html. For more details about
398
mo d _pro xy from the perspective of JBoss EAP 6, see Section 17.8.1, About the Apache mod_proxy
HTTP Connector and Section 17.2.3, Overview of HTTP Connectors .
Prereq u isit es
Apache HTTP server either from JBoss Enterprise Web Server or provided by operating system
needs to be installed. A standalone Apache HTTP server is provided as a separate download in
the Red Hat Customer Portal, in the JBoss EAP 6 download area. See Section 17.4.3, Install
Apache HTTP Server in Red Hat Enterprise Linux 5, 6, and 7 (Z ip) for information about this
Apache HTTP server if you wish to use it.
The mo d _pro xy modules need to be installed. Apache HTTP server typically comes with the
mo d _pro xy modules already included. This is the case on Red Hat Enterprise Linux and the
Apache HTTP Server that comes with the JBoss Enterprise Web Server.
You need ro o t or administrator privileges to modify the Apache HTTP Server configuration.
In our example we assume that JBoss EAP 6 is configured with the HTTP or HTTPS web
connector. This is part of the Web subsystem configuration. Refer to Section 15.1, Configure the
Web Subsystem for information about configuring the Web subsystem.
1. En ab le t h e mo d _pro xy mo d u les in t h e h t t p d
Look for the following lines in your HTTPD_CONF/httpd . co nf file. If they are not present,
add them to the bottom. If they are present but the lines begin with a comment (#) character,
remove the character. Save the file afterward. Usually, the modules are already present and
enabled.
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
LoadModule proxy_http_module modules/mod_proxy_http.so
# Uncomment these to proxy FTP or HTTPS
#LoadModule proxy_ftp_module modules/mod_proxy_ftp.so
#LoadModule proxy_connect_module modules/mod_proxy_connect.so
2. Ad d a n o n - lo ad - b alan cin g p ro xy.
Add the following configuration to your HTTPD_CONF/httpd . co nf file, directly beneath any
other <Vi rtual Ho st> directives you may have. Replace the values with ones appropriate to
your setup.
This example uses a virtual host. See the next step to use the default httpd configuration.
<VirtualHost *:80>
# Your domain name
ServerName Domain_NAME_HERE
ProxyPreserveHost On
# The IP and port of JBoss EAP 6
# These represent the default values, if your httpd is on the same
host
# as your JBoss EAP 6 managed domain or server
ProxyPass / http://localhost:8080/
ProxyPassReverse / http://localhost:8080/
399
# The location of the HTML files, and access control information

DocumentRoot /var/www
<Directory /var/www>
Options -Indexes
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
After making your changes, save the file.
3. Ad d a lo ad - b alan cin g p ro xy.
To use mo d _pro xy as a load balancer, and send work to multiple JBoss EAP 6 instances,
add the following configuration to your HTTPD_CONF/httpd . co nf file. The example IP
addresses are fictional. Replace them with the appropriate values for your environment.
<Proxy balancer://mycluster>
Order deny,allow
Allow from all
# Add each JBoss Enterprise Application Server by IP address and
port.
# If the route values are unique like this, one node will not fail
over to the other.
BalancerMember http://192.168.1.1:8080 route=node1
BalancerMember http://192.168.1.2:8180 route=node2
</Proxy>
<VirtualHost *:80>
# Your domain name
ServerName YOUR_DOMAIN_NAME
ProxyPreserveHost On
ProxyPass / balancer://mycluster/
# The location of the HTML files, and access control information
DocumentRoot /var/www
<Directory /var/www>
Options -Indexes
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
The examples above all communicate using the HTTP protocol. You can use AJP or HTTPS
protocols instead, if you load the appropriate mo d _pro xy modules. Refer to Apache's
mo d _pro xy documentation http://httpd.apache.org/docs/2.2/mod/mod_proxy.html for more
details.
4. En ab le st icky sessio n s.
4 00
Sticky sessions mean that if a client request originally goes to a specific JBoss EAP 6 worker,
all future requests will be sent to the same worker, unless it becomes unavailable. This is
almost always the correct behavior.
To enable sticky sessions for mo d _pro xy, add the sti ckysessi o n parameter to the
P ro xyP ass statement. This example also shows some other parameters which you can use.
See Apache's mo d _pro xy documentation at
http://httpd.apache.org/docs/2.2/mod/mod_proxy.html for more information on them.
ProxyPass /MyApp balancer://mycluster stickysession=JSESSIONID
lbmethod=bytraffic nofailover=Off
5. R est art t h e Web Server.
Restart the web server for your changes to take effect.
R esu lt
Your Apache HTTP server is configured to use mo d _pro xy to send client requests to JBoss EAP 6
instances, either in a standard or load-balancing configuration. To configure JBoss EAP 6 to
respond to these requests, see Section 17.4.8, Configure JBoss EAP 6 to Accept Requests From
External Web Servers .
Report a bug
17.9. Microsoft ISAPI Connect or

17.9.1. About t he Int ernet Server API (ISAPI)
Internet Server API (ISAPI) is a set of APIs used to write OLE Server extensions and filters for Web
servers such as Microsoft's Internet Information Services (IIS). i sapi _red i rect. d l l is an
extension of mo d _jk adjusted to IIS. i sapi _red i rect. d l l enables you to configure JBoss EAP
6 instances as a worker nodes with an IIS as load balancer.
Report a bug
17.9.2. Download and Ext ract Webserver Connect or Nat ives for Microsoft IIS
1. In a web browser, navigate to the Red Hat Customer Support portal at
https://access.redhat.com.
2. Navigate to D o wnl o ad s, then R ed Hat JBo ss Mi d d l eware D o wnl o ad So ftware,
then select Enterpri se Appl i cati o n P l atfo rm from the P ro d uct drop-down list.
3. Select the appropriate version from the Versi o n drop-down list.
4. Choose the D o wnl o ad option of either R ed Hat JBo ss Enterpri se Appl i cati o n
P l atfo rm <VERSION> Webserver C o nnecto r Nati ves fo r Wi nd o ws Server
20 0 8 x86 _6 4 or R ed Hat JBo ss Enterpri se Appl i cati o n P l atfo rm <VERSION>
Webserver C o nnecto r Nati ves fo r Wi nd o ws Server 20 0 8 i 6 86 depending on
the architecture of the server.
5. Open the Z ip file and copy the contents of the jbo sseap-<VERSION>/mo d ul es/system/l ayers/base/nati ve/sbi n directory to a location
on your server. It is assumed the contents were copied to C : \co nnecto rs\.
4 01
Report a bug
17.9.3. Configure Microsoft IIS t o Use t he ISAPI Connect or

Prereq u isit es:
Section 17.9.2, D ownload and Extract Webserver Connector Natives for Microsoft IIS
Note
See https://access.redhat.com/articles/111663 for a list of supported configurations of
Microsoft Windows Server and IIS.
Pro ced u re 17.22. C o n f ig u re t h e IIS R ed irect o r U sin g t h e IIS Man ag er ( IIS 7)

1. Open the IIS manager by clicking St art R u n , and typing i netmg r.
2. In the tree view pane at the left, expand IIS 7.
3. D ouble-click ISAP I and C G I R eg i strati o ns to open it in a new window.
4. In the Acti o ns pane, click Ad d . The Ad d ISAP I o r C G I R estri cti o n window opens.
5. Specify the following values:
ISAP I o r C G I P ath: c: \co nnecto rs\i sapi _red i rect. d l l
D escri pti o n: jbo ss
Al l o w extensi o n path to execute: select the check box.
6. Click O K to close the Ad d ISAP I o r C G I R estri cti o n window.
7. D ef in e a JB o ss N at ive virt u al d irect o ry
a. Right-click D efaul t Web Si te, and click Ad d Vi rtual D i recto ry. The Ad d
Vi rtual D i recto ry window opens.
b. Specify the following values to add a virtual directory:
Al i as: jbo ss
P hysi cal P ath: C : \co nnecto rs\
c. Click O K to save the values and close the Ad d Vi rtual D i recto ry window.
8. D ef in e a JB o ss N at ive ISAPI R ed irect Filt er
a. In the tree view pane, expand Sit es D ef au lt Web Sit e.
b. D ouble-click ISAP I Fi l ters. The ISAP I Fi l ters Features view appears.
c. In the Acti o ns pane, click Ad d . The Ad d ISAP I Fi l ter window appears.
d. Specify the following values in the Ad d ISAP I Fi l ter window:
Fi l ter name: jbo ss
4 02
Executabl e: C : \co nnecto rs\i sapi _red i rect. d l l

e. Click O K to save the values and close the Ad d ISAP I Fi l ters window.
9. En ab le t h e ISAPI- d ll h an d ler
a. D ouble-click the IIS 7 item in the tree view pane. The IIS 7 Ho me Features
Vi ew opens.
b. D ouble-click Hand l er Mappi ng s. The Hand l er Mappi ng s Features Vi ew
appears.
c. In the G ro up by combo box, select State. The Hand l er Mappi ng s are displayed
in Enabl ed and D i sabl ed G ro ups.
d. Find ISAP I-d l l . If it is in the D i sabl ed group, right-click it and select Ed i t
Feature P ermi ssi o ns.
e. Enable the following permissions:
Read
Script
Execute
f. Click O K to save the values, and close the Ed i t Feature P ermi ssi o ns window.
R esu lt
Microsoft IIS is now configured to use the ISAPI Connector. Next, Section 17.4.8, Configure JBoss
EAP 6 to Accept Requests From External Web Servers , then Section 17.9.4, Configure the ISAPI
Connector to Send Client Requests to JBoss EAP 6 or Section 17.9.5, Configure the ISAPI
Connector to Balance Client Requests Across Multiple JBoss EAP 6 Servers .
Report a bug
17.9.4 . Configure t he ISAPI Connect or t o Send Client Request s t o JBoss EAP

6
O verview
This task configures a group of JBoss EAP 6 servers to accept requests from the ISAPI connector. It
does not include configuration for load-balancing or high-availability failover. If you need these
capabilities, refer to Section 17.9.5, Configure the ISAPI Connector to Balance Client Requests
Across Multiple JBoss EAP 6 Servers .
This configuration is done on the IIS server, and assumes that JBoss EAP 6 is already configured as
per Section 17.4.8, Configure JBoss EAP 6 to Accept Requests From External Web Servers .
Prereq u isit es
You need full administrator access to the IIS server
Pro ced u re 17.23. Ed it Pro p ert y Files an d Set u p R ed irect io n
4 03
1. C reat e a d irect o ry t o st o re lo g s, p ro p ert y f iles, an d lo ck f iles.

The rest of this procedure assumes that you are using the directory C : \co nnecto rs\ for
this purpose. If you use a different directory, modify the instructions accordingly.
2. C reat e t h e i sapi _red i rect. pro perti es f ile.
Create a new file called C : \co nnecto rs\i sapi _red i rect. pro perti es. Copy the
following contents into the file.
# Configuration file for the ISAPI Connector
# Extension uri definition
extension_uri=/jboss/isapi_redirect.dll
# Full path to the log file for the ISAPI Connector
log_file=c:\connectors\isapi_redirect.log
# Log level (debug, info, warn, error or trace)
log_level=info
# Full path to the workers.properties file
worker_file=c:\connectors\workers.properties
# Full path to the uriworkermap.properties file
worker_mount_file=c:\connectors\uriworkermap.properties
#Full path to the rewrite.properties file
rewrite_rule_file=c:\connectors\rewrite.properties
If you do not want to use a rewri te. pro perti es file, comment out the last line by placing a
# character at the beginning of the line. See Step 5 for more information.
3. C reat e t h e uri wo rkermap. pro perti es f ile
The uri wo rkermap. pro perti es file contains mappings between deployed application
URLs and which worker handles requests to them. The following example file shows the
syntax of the file. Place your uri wo rkermap. pro perti es file into C : \co nnecto rs\.
# images and css files for path /status are provided by worker01
/status=worker01
/images/*=worker01
/css/*=worker01
# Path /web-console is provided by worker02
# IIS (customized) error page is used for http errors with number
greater or equal to 400
# css files are provided by worker01
/web-console/*=worker02;use_server_errors=400
/web-console/css/*=worker01
# Example of exclusion from mapping, logo.gif won't be displayed
# /web-console/images/logo.gif=*
# Requests to /app-01 or /app-01/something will be routed to
worker01
/app-01|/*=worker01
4 04
# Requests to /app-02 or /app-02/something will be routed to

worker02
/app-02|/*=worker02
4. C reat e t h e wo rkers. pro perti es f ile.
The wo rkers. pro perti es file contains mapping definitions between worker labels and
server instances. The following example file shows the syntax of the file. Place this file into the
C : \co nnecto rs\ directory.
# An entry that lists all the workers defined
worker.list=worker01, worker02
# Entries that define the host and port associated with these
workers
# First JBoss EAP 6 server definition, port 8009 is standard port
for AJP in EAP
worker.worker01.host=127.0.0.1
worker.worker01.port=8009
worker.worker01.type=ajp13
# Second JBoss EAP 6 server definition
5.
C reat e t h e rewri te. pro perti es f ile.
The rewri te. pro perti es file contains simple URL rewriting rules for specific applications.
The rewritten path is specified using name-value pairs, as shown in the example below. Place
this file into the C : \co nnecto rs\ directory.
#Simple example
# Images are accessible under abc path
/app-01/abc/=/app-01/images/
6. R est art t h e IIS server.
Restart your IIS server by using the net sto p and net start commands.
C:\> net stop was /Y
C:\> net start w3svc
R esu lt
The IIS server is configured to send client requests to the specific JBoss EAP 6 servers you have
configured, on an application-specific basis.
Report a bug
4 05
17.9.5. Configure t he ISAPI Connect or t o Balance Client Request s Across

Mult iple JBoss EAP 6 Servers
O verview
This configuration balances client requests across the JBoss EAP 6 servers you specify. If you prefer
to send client requests to specific JBoss EAP 6 servers on a per-deployment basis, refer to
Section 17.9.4, Configure the ISAPI Connector to Send Client Requests to JBoss EAP 6 instead.
This configuration is done on the IIS server, and assumes that JBoss EAP 6 is already configured as
per Section 17.4.8, Configure JBoss EAP 6 to Accept Requests From External Web Servers .
Prereq u isit es
Full administrator access on the IIS server.
Pro ced u re 17.24 . B alan ce C lien t R eq u est s Acro ss Mu lt ip le Servers
1. C reat e a d irect o ry t o st o re lo g s, p ro p ert y f iles, an d lo ck f iles.
The rest of this procedure assumes that you are using the directory C : \co nnecto rs\ for
this purpose. If you use a different directory, modify the instructions accordingly.
2. C reat e t h e i sapi _red i rect. pro perti es f ile.
Create a new file called C : \co nnecto rs\i sapi _red i rect. pro perti es. Copy the
following contents into the file.
# Configuration file for the ISAPI Connector
# Extension uri definition
extension_uri=/jboss/isapi_redirect.dll
# Full path to the log file for the ISAPI Connector
log_file=c:\connectors\isapi_redirect.log
# Log level (debug, info, warn, error or trace)
log_level=info
# Full path to the workers.properties file
worker_file=c:\connectors\workers.properties
# Full path to the uriworkermap.properties file
worker_mount_file=c:\connectors\uriworkermap.properties
#OPTIONAL: Full path to the rewrite.properties file
rewrite_rule_file=c:\connectors\rewrite.properties
If you do not want to use a rewri te. pro perti es file, comment out the last line by placing a
# character at the beginning of the line. See Step 5 for more information.
3. C reat e t h e uri wo rkermap. pro perti es f ile.
4 06
The uri wo rkermap. pro perti es file contains mappings between deployed application
URLs and which worker handles requests to them. The following example file shows the
syntax of the file, with a load-balanced configuration. The wildcard (*) character sends all
requests for various URL sub-directories to the load-balancer called ro uter. The
configuration of the load-balancer is covered in Step 4.
Place your uri wo rkermap. pro perti es file into C : \co nnecto rs\.
# images, css files, path /status and /web-console will be
# provided by nodes defined in the load-balancer called "router"
/css/*=router
/images/*=router
/status=router
/web-console|/*=router
# Example of exclusion from mapping, logo.gif won't be displayed
# /web-console/images/logo.gif=*
# Requests to /app-01 and /app-02 will be routed to nodes defined
# in the load-balancer called "router"
/app-01|/*=router
/app-02|/*=router
# mapping for management console, nodes in cluster can be enabled
or disabled here
/jkmanager|/*=status
4.
C reat e t h e wo rkers. pro perti es f ile.
The wo rkers. pro perti es file contains mapping definitions between worker labels and
server instances. The following example file shows the syntax of the file. The load balancer is
configured near the end of the file, to comprise workers wo rker0 1 and wo rker0 2. The
wo rkers. pro perti es file follows the syntax of the same file used for Apache mod_jk
configuration. For more information about the syntax of the wo rkers. pro perti es file, refer
to Section 17.7.5, Configuration Reference for Apache mod_jk Workers .
Place this file into the C : \co nnecto rs\ directory.
# The advanced router LB worker
worker.list=router,status
# First EAP server definition, port 8009 is standard port for AJP
in EAP
#
# lbfactor defines how much the worker will be used.
# The higher the number, the more requests are served
# lbfactor is useful when one machine is more powerful
# ping_mode=A all possible probes will be used to determine that
# connections are still working
worker.worker01.ping_mode=A
4 07
worker.worker01.socket_timeout=10
worker.worker01.lbfactor=3
# Second EAP server definition
# Define the LB worker
worker.router.type=lb
worker.router.balance_workers=worker01,worker02
# Define the status worker for jkmanager
5.
C reat e t h e rewri te. pro perti es f ile.
The rewri te. pro perti es file contains simple URL rewriting rules for specific applications.
The rewritten path is specified using name-value pairs, as shown in the example below. Place
this file into the C : \co nnecto rs\ directory.
#Simple example
# Images are accessible under abc path
/app-01/abc/=/app-01/images/
6. R est art t h e IIS server.
Restart your IIS server by using the net sto p and net start commands.
C:\> net stop was /Y
C:\> net start w3svc
R esu lt
The IIS server is configured to send client requests to the JBoss EAP 6 servers referenced in the
wo rkers. pro perti es file, spreading the load across the servers in a 1:3 ratio. This ratio is derived
from the load balancing factor (l bfacto r) assigned to each server.
Report a bug
17.10. Oracle NSAPI Connect or

17.10.1. About t he Net scape Server API (NSAPI)
Netscape Server API (NSAPI) is an API provided by Oracle iPlanet Web Server (formerly Netscape Web
Server) for implementing extensions to the server. These extensions are known as server plugins.
This API is used in nsapi _red i recto r. so provided by JBoss EAP 6 in Nati ve uti l i ti es
packages. To configure this connector, refer to Section 17.10.4, Configure the NSAPI Connector to
Balance Client Requests Across Multiple JBoss EAP 6 Servers .
4 08
Report a bug
17.10.2. Configure t he NSAPI Connect or on Oracle Solaris

Su mmary
The NSAPI connector is a module that runs within Oracle iPlanet Web Server.
Prereq u isit es
Your server is running Oracle Solaris 10 or greater, on either an Intel 32-bit, an Intel 64-bit, or a
SPARC64 architecture.
Oracle iPlanet Web Server 7.0.15 or later for Intel architectures, or 7.0.14 or later for SPARC
architectures, is installed and configured, aside from the NSAPI connector.
JBoss EAP 6 is installed and configured on each server which will serve as a worker. Refer to
Section 17.4.8, Configure JBoss EAP 6 to Accept Requests From External Web Servers .
The JBoss Native Components Z IP package is downloaded from the Customer Service Portal at
Pro ced u re 17.25. Ext ract an d Set u p t h e N SAPI C o n n ect o r
1. Ext ract t h e JB o ss N at ive C o mp o n en t s p ackag e.
The rest of this procedure assumes that the Native Components package is extracted to the
EAP_HOME directory. For the rest of this procedure, the directory
/o pt/o racl e/webserver7/co nfi g / is referred to as IPLANET_CONFIG. If your Oracle
iPlanet configuration directory is different, modify the procedure accordingly.
2. D isab le servlet map p in g s.
Open the IPLANET_CONFIG/d efaul t. web. xml file and locate the section with the
heading Bui l t In Server Mappi ng s. D isable the mappings to the following three
servlets, by wrapping them in XML comment characters (<! -- and -->).
default
invoker
jsp
The following example configuration shows the disabled mappings.





<servlet-name>invoker</servlet-name>
<url-pattern>/servlet/*</url-pattern>
4 09

<servlet-name>jsp</servlet-name>
<url-pattern>*.jsp</url-pattern>
Save and exit the file.
3. C o n f ig u re t h e iPlan et Web Server t o lo ad t h e N SAPI co n n ect o r mo d u le.
Add the following lines to the end of the IPLANET_CONFIG/mag nus. co nf file, modifying file
paths to suit your configuration. These lines define the location of the
nsapi _red i recto r. so module, as well as the wo rkers. pro perti es file, which lists the
workers and their properties.
Init fn="load-modules" funcs="jk_init,jk_service"
shlib="EAP_HOME/modules/system/layers/base/native/lib/nsapi_redirec
tor.so" shlib_flags="(global|now)"
Init fn="jk_init"
worker_file="IPLANET_CONFIG/connectors/workers.properties"
log_level="info" log_file="IPLANET_CONFIG/connectors/nsapi.log"
shm_file="IPLANET_CONFIG/connectors/tmp/jk_shm"
The configuration above is for a 32-bit architecture. If you use 64-bit Solaris, change the
string l i b/nsapi _red i recto r. so to l i b6 4 /nsapi _red i recto r. so .
4. C o n f ig u re t h e N SAPI co n n ect o r.
You can configure the NSAPI connector for a basic configuration, with no load balancing, or
a load-balancing configuration. Choose one of the following options, after which your
configuration will be complete.
Section 17.10.3, Configure the NSAPI Connector to Send Client Requests to JBoss EAP
6
Section 17.10.4, Configure the NSAPI Connector to Balance Client Requests Across
Multiple JBoss EAP 6 Servers
Report a bug
17.10.3. Configure t he NSAPI Connect or t o Send Client Request s t o JBoss

EAP 6
O verview
This task configures the NSAPI connector to redirect client requests to JBoss EAP 6 servers with no
load-balancing or fail-over. The redirection is done on a per-deployment (and hence per-URL) basis.
For a load-balancing configuration, refer to Section 17.10.4, Configure the NSAPI Connector to
Balance Client Requests Across Multiple JBoss EAP 6 Servers instead.
Prereq u isit es
4 10
You must complete Section 17.10.2, Configure the NSAPI Connector on Oracle Solaris before
continuing with the current task.
Pro ced u re 17.26 . Set u p t h e B asic H T T P C o n n ect o r
1. D ef in e t h e U R L p at h s t o red irect t o t h e JB o ss EAP 6 servers.
Note
In IPLANET_CONFIG/o bj. co nf, spaces are not allowed at the beginning of a line,
except when the line is a continuation of the previous line.
Edit the IPLANET_CONFIG/o bj. co nf file. Locate the section which starts with <O bject
name= "d efaul t">, and add each URL pattern to match, in the format shown by the example
file below. The string jknsapi refers to the HTTP connector which will be defined in the next
step. The example shows the use of wildcards for pattern matching.
<Object name="default">
[...]
NameTrans fn="assign-name"
</Object>
from="/status" name="jknsapi"
from="/images(|/*)" name="jknsapi"
from="/css(|/*)" name="jknsapi"
from="/nc(|/*)" name="jknsapi"
from="/jmx-console(|/*)" name="jknsapi"
2. D ef in e t h e wo rker wh ich serves each p at h .

Continue editing the IPLANET_CONFIG/o bj. co nf file. Add the following directly after the
closing tag of the section you have just finished editing: </O bject>.
<Object name="jknsapi">
ObjectType fn=force-type type=text/plain
Service fn="jk_service" worker="worker01" path="/status"
Service fn="jk_service" worker="worker02" path="/nc(/*)"
Service fn="jk_service" worker="worker01"
</Object>
The example above redirects requests to the URL path /status to the worker called
wo rker0 1, and all URL paths beneath /nc/ to the worker called wo rker0 2. The third line
indicates that all URLs assigned to the jknsapi object which are not matched by the
previous lines are served to wo rker0 1.
3.
D ef in e t h e wo rkers an d t h eir at t rib u t es.
Create a file called wo rkers. pro perti es in the IP LANET _C O NFIG /co nnecto rs/
directory. Paste the following contents into the file, and modify them to suit your environment.
4 11
# An entry that lists all the workers defined

worker.list=worker01, worker02
# Entries that define the host and port associated with these
workers
The wo rkers. pro perti es file uses the same syntax as Apache mod_jk. For information
about which options are available, refer to Section 17.7.5, Configuration Reference for
Apache mod_jk Workers .
4. R est art t h e iPlan et Web Server.
Issue the following command to restart the iPlanet Web Server.
IPLANET_CONFIG/../bin/stopserv
IPLANET_CONFIG/../bin/startserv
R esu lt
iPlanet Web Server now sends client requests to the URLs you have configured to deployments on
JBoss EAP 6.
Report a bug
17.10.4 . Configure t he NSAPI Connect or t o Balance Client Request s Across

Mult iple JBoss EAP 6 Servers
O verview
This task configures the NSAPI connector to send client requests to JBoss EAP 6 servers in a loadbalancing configuration. To use NSAPI connector as a simple HTTP connector with no loadbalancing, see Section 17.10.3, Configure the NSAPI Connector to Send Client Requests to JBoss
EAP 6 .
Prereq u isit es
Section 17.10.2, Configure the NSAPI Connector on Oracle Solaris
Pro ced u re 17.27. C o n f ig u re t h e C o n n ect o r f o r Lo ad - B alan cin g
1. D ef in e t h e U R L p at h s t o red irect t o t h e JB o ss EAP 6 servers.
4 12
Note
In IPLANET_CONFIG/o bj. co nf, spaces are not allowed at the beginning of a line,
except when the line is a continuation of the previous line.
Edit the IPLANET_CONFIG/o bj. co nf file. Locate the section which starts with <O bject
name= "d efaul t">, and add each URL pattern to match, in the format shown by the example
file below. The string jknsapi refers to the HTTP connector which will be defined in the next
step. The example shows the use of wildcards for pattern matching.
<Object name="default">
[...]
</Object>
from="/status" name="jknsapi"
from="/images(|/*)" name="jknsapi"
from="/css(|/*)" name="jknsapi"
from="/nc(|/*)" name="jknsapi"
from="/jmx-console(|/*)" name="jknsapi"
from="/jkmanager/*" name="jknsapi"
2. D ef in e t h e wo rker t h at serves each p at h .

Continue editing the IPLANET_CONFIG/o bj. co nf file. D irectly after the closing tag for the
section you modified in the previous step (</O bject>), add the following new section and
modify it to your needs:
<Object name="jknsapi">
ObjectType fn=force-type type=text/plain
Service fn="jk_service" worker="status" path="/jkmanager(/*)"
Service fn="jk_service" worker="router"
</Object>
This jksnapi object defines the worker nodes used to serve each path that was mapped to
the name= "jksnapi " mapping in the d efaul t object. Everything except for URLs matching
/jkmanag er/* is redirected to the worker called ro uter.
3. D ef in e t h e wo rkers an d t h eir at t rib u t es.
Create a file called wo rkers. pro perti es in IP LANET _C O NFIG /co nnecto r/. Paste the
following contents into the file, and modify them to suit your environment.
# The advanced router LB worker
# A list of each worker
worker.list=router,status
# First JBoss EAP server
# (worker node) definition.
# Port 8009 is the standard port for AJP
#
4 13
# Second JBoss EAP server
# Define the load-balancer called "router"
worker.router.type=lb
worker.router.balance_workers=worker01,worker02
# Define the status worker
The wo rkers. pro perti es file uses the same syntax as Apache mod_jk. For information
about which options are available, see Section 17.7.5, Configuration Reference for Apache
mod_jk Workers .
4. R est art t h e iPlan et Web Server 7.0.
IPLANET_CONFIG/../bin/stopserv
IPLANET_CONFIG/../bin/startserv
R esu lt
The iPlanet Web Server redirects the URL patterns you have configured to your JBoss EAP 6 servers
in a load-balancing configuration.
Report a bug
4 14
Chapter 18. Messaging

18.1.1. Hornet Q
HornetQ is a multi-protocol, asynchronous messaging system developed by Red Hat. HornetQ
provides high availability (HA) with automatic client failover to guarantee message reliability in the
event of a server failure. HornetQ also supports flexible clustering solutions with load-balanced
messages.
HornetQ is the Java Message Service (JMS) provider for JBoss EAP 6 and is configured as the
Messag i ng Subsystem
Report a bug
18.1.2. Handling Slow Hornet Q Consumers

A slow consumer with a server-side queue (e.g. JMS topic subscriber) can pose a significant problem
for broker performance. If messages build up in the consumer's server-side queue then memory will
begin filling up and the broker may enter paging mode which would impact performance negatively.
However, criteria can be set so that consumers which don't acknowledge messages quickly enough
can potentially be disconnected from the broker which in the case of a non-durable JMS subscriber
would allow the broker to remove the subscription and all of its messages freeing up valuable server
resources.
Report a bug
18.1.3. Handling Blocking Calls During fail-over

If the client code is in a blocking call to the server, waiting for a response to continue its execution,
when fail-over occurs, the new session will not have any knowledge of the call that was in progress.
This call might otherwise hang for ever, waiting for a response that will never come.
To prevent this, HornetQ will unblock any blocking calls that were in progress at the time of fail-over
by making them throw a javax. jms. JMSExcepti o n (if using JMS), or a Ho rnetQ Excepti o n with
error code Ho rnetQ Excepti o n. UNBLO C KED . It is up to the client code to catch this exception and
retry any operations if desired.
If the method being unblocked is a call to commit(), or prepare(), then the transaction will be
automatically rolled back and HornetQ will throw a
javax. jms. T ransacti o nR o l l ed BackExcepti o n (if using JMS), or a Ho rnetQ Excepti o n
with error code Ho rnetQ Excepti o n. T R ANSAC T IO N_R O LLED _BAC K if using the core API.
Report a bug
18.1.4 . Handling fail-over Wit h T ransact ions

If the session is transactional and messages have already been sent or acknowledged in the current
transaction, then the server cannot be sure that messages sent or acknowledgments have not been
lost during the fail-over.
Consequently the transaction will be marked as rollback-only, and any subsequent attempt to commit
will throw a javax. jms. T ransacti o nR o l l ed BackExcepti o n (if using JMS), or a
Ho rnetQ Excepti o n with error code Ho rnetQ Excepti o n. T R ANSAC T IO N_R O LLED _BAC K if using
4 15
the core API.

It is up to the user to catch the exception, and perform any client side local rollback code as
necessary. There is no need to manually rollback the session - it is already rolled back. The user can
then retry the transactional operations again on the same session.
If fail-over occurs when a commit call is being executed, the server, as previously described, will
unblock the call to prevent a hang, since no response will come back. In this case it is not easy for
the client to determine whether the transaction commit was actually processed on the live server
before failure occurred.
To remedy this, the client can enable duplicate detection in the transaction, and retry the transaction
operations again after the call is unblocked. If the transaction had indeed been committed on the live
server successfully before fail-over, then when the transaction is retried, duplicate detection will
ensure that any durable messages resent in the transaction will be ignored on the server to prevent
them getting sent more than once.
Note
By catching the rollback exceptions and retrying, catching unblocked calls and enabling
duplicate detection, once and only once delivery guarantees for messages can be provided in
the case of failure, guaranteeing 100% no loss or duplication of messages.
Report a bug
18.1.5. Handling fail-over Wit h Non T ransact ional Sessions

If the session is non transactional, messages or acknowledgments can be lost in the event of failover.
To provide once and only once delivery guarantees for non transacted sessions too, enabled
duplicate detection, and catch unblock exceptions.
Report a bug
18.1.6. Get t ing Not ified of Connect ion Failure

JMS provides a standard mechanism for getting notified asynchronously of connection failure:
java. jms. Excepti o nLi stener. For more information about ExceptionListener, refer Oracle
javax.jms Javadoc.
The HornetQ core API also provides a similar feature in the form of the class
o rg . ho rnet. co re. cl i ent. Sessi o nFai l ureLi stener.
Any JMS Excepti o nLi stener or Core Sessi o nFai l ureLi stener instance will always be called
by HornetQ in the event of connection failure, irrespective of whether the connection was successfully
failed over, reconnected or reattached.
Report a bug
18.1.7. About Java Messaging Service (JMS)

Messaging systems allow you to loosely couple heterogeneous systems together with added
reliability. Java Messaging Service (JMS) providers use a system of transactions, to commit or roll
back changes atomically. Unlike systems based on a Remote Procedure Call (RPC) pattern,
4 16
Chapt er 1 8 . Messaging
messaging systems primarily use an asynchronous message passing pattern with no tight
relationship between requests and responses. Most messaging systems also support a requestresponse mode but this is not a primary feature of messaging systems.
Messaging systems decouple the senders of messages from the consumers of messages. The
senders and consumers of messages are completely independent and know nothing of each other.
This allows you to create flexible, loosely coupled systems. Often, large enterprises use a messaging
system to implement a message bus which loosely couples heterogeneous systems together.
Message buses often form the core of an Enterprise Service Bus (ESB). Using a message bus to
decouple disparate systems can allow the system to grow and adapt more easily. It also allows more
flexibility to add new systems or retire old ones since they don't have brittle dependencies on each
other.
Report a bug
18.1.8. Support ed Messaging St yles

HornetQ supports the following messaging styles:
Messag e Q u eu e p at t ern
The Message Queue pattern involves sending a message to a queue. Once in the queue,
the message is usually made persistent to guarantee delivery. Once the message has
moved through the queue, the messaging system delivers it to a message consumer. The
message consumer acknowledges the delivery of the message once it is processed.
When used with point-to-point messaging, the Message Queue pattern allows multiple
consumers for a queue, but each message can only be received by a single consumer.
Pu b lish - Su b scrib e p at t ern
The Publish-Subscribe pattern allows multiple senders to send messages to a single entity
on the server. This entity is often known as a " topic" . Each topic can be attended by
multiple consumers, known as " subscriptions" .
Each subscription receives a copy of every message sent to the topic. This differs from the
Message Queue pattern, where each message is only consumed by a single consumer.
Subscriptions that are durable retain copies of each message sent to the topic until the
subscriber consumes them. These copies are retained even in the event of a server restart.
Non-durable subscriptions last only as long as the connection that created them.
Report a bug
18.2. Configurat ion of T ransport s

18.2.1. About Accept ors and Connect ors
HornetQ uses the concept of connectors and acceptors as a key part of the messaging system.
Accep t o rs an d C o n n ect o rs
Accepto r
An acceptor defines which types of connections are accepted by the HornetQ server.
C o nnecto r
4 17
A connector defines how to connect to a HornetQ server, and is used by the HornetQ client.
There are two types of connectors and acceptors, relating to whether the matched connector and
acceptor pair occur within same JVM or not.
In vm an d N et t y
Invm
Invm is short for Intra Virtual Machine. It can be used when both the client and the server
are running in the same JVM.
Netty
The name of a JBoss project. It must be used when the client and server are running in
different JVMs.
A HornetQ client must use a connector that is compatible with one of the server's acceptors. Only an
Invm connector can connect to an Invm acceptor, and only a netty connector can connect to a netty
acceptor. The connectors and acceptors are both configured on the server in a stand al o ne. xml
and d o mai n. xml . You can use either the Management Console or the Management CLI to define
them.
Report a bug
18.2.2. Configuring Net t y T CP

Netty TCP is a simple unencrypted TCP sockets based transport. Netty TCP can be configured to use
old blocking Java IO or non blocking Java NIO. Java NIO is recommended on the server side for
better scalability with many concurrent connections. If the number of concurrent connections is less
Java old IO can give better latency than NIO.
Netty TCP is not recommended for running connections across an untrusted network as it is
unencrypted. With the Netty TCP transport all connections are initiated from the client side.
Examp le 18.1. Examp le o f N et t y T C P C o n f ig u rat io n f ro m D ef au lt EAP C o n f ig u rat io n
<connectors>
<netty-connector name="netty" socket-binding="messaging"/>
<netty-connector name="netty-throughput" socket-binding="messagingthroughput">
<param key="batch-delay" value="50"/>
</netty-connector>
<in-vm-connector name="in-vm" server-id="0"/>
</connectors>
<acceptors>
<netty-acceptor name="netty" socket-binding="messaging"/>
<netty-acceptor name="netty-throughput" socket-binding="messagingthroughput">
<param key="direct-deliver" value="false"/>
</netty-acceptor>
<in-vm-acceptor name="in-vm" server-id="0"/>
</acceptors>
4 18
The example configuration also shows how the JBoss EAP 6 implementation of HornetQ uses socket
bindings in the acceptor and connector configuration. This differs from the standalone version of
HornetQ, which requires you to declare the specific hosts and ports.
The following table describes Netty TCP configuration properties:
T ab le 18.1. N et t y T C P C o n f ig u rat io n Pro p ert ies
Pro p ert y
D ef au lt
D escrip t io n
batch-delay
0 milliseconds
direct-deliver
true
local-address
[local address available]
local-port
Before writing packets to the

transport, HornetQ can be
configured to batch up writes
for a maximum of batch-delay
milliseconds. This increases
the overall throughput for very
small messages by increasing
average latency for message
transfer
When a message arrives on the
server and is delivered to
waiting consumers, by default,
the delivery is done on the
same thread on which the
message arrived. This gives
good latency in environments
with relatively small messages
and a small number of
consumers but reduces the
throughput and latency. For
highest throughput you can set
this property as " false"
For a netty connector, this is
used to specify the local
address which the client will
use when connecting to the
remote address. If a local
address is not specified then
the connector will use any
available local address
For a netty connector, this is
used to specify which local port
the client will use when
connecting to the remote
address. If the local-port default
is used (0) then the connector
will let the system pick up an
ephemeral port. valid ports are
0 to 65535
4 19
Pro p ert y
D ef au lt
D escrip t io n
nio-remoting-threads
-1
tcp-no-delay
true
tcp-send-buffer-size
32768 bytes
tcp-receive-buffer-size
32768 bytes
use-nio
false
use-nio-global-worker-pool
false
If configured to use NIO,

HornetQ will, by default, use a
number of threads equal to
three times the number of cores
(or hyper-threads) as reported
by
Runtime.getRuntime().available
Processors() for processing
incoming packets. To override
this value, you can set a
custom value for the number of
threads
If this is true then Nagle's
algorithm will be enabled. This
algorithm helps improve the
efficiency of TCP/IP networks
by reducing the number of
packets sent over a network
This parameter determines the
size of the TCP send buffer in
bytes
This parameter determines the
size of the TCP receive buffer in
bytes
If this is true then Java non
blocking NIO will be used. If set
to false then old blocking Java
IO will be used.If you need the
server to handle many
concurrent connections use
non blocking Java NIO
otherwise go for old (blocking)
IO
This parameter will ensure all
JMS connections share a
single pool of Java threads
(rather than each connection
having its own pool). This
serves to avoid exhausting the
maximum number of processes
on the operating system.
4 20
Important
If you have use-ni o set to true, use the use-ni o -g l o bal -wo rker-po o l parameter to
minimize the risk that a machine may create a large number of connections, which could lead
to an O utO fMemo ry error.
<netty-connector name="netty" socket-binding="messaging">
<param key="use-nio" value="true"/>
<param key="use-nio-global-worker-pool" value="true"/>
</netty-connector>
Note
Netty TCP properties are valid for all types of transport (Netty SSL, Netty HTTP and Netty
Servlet).
Report a bug
18.2.3. Configuring Net t y Secure Socket s Layer (SSL)

Netty TCP is a simple unencrypted TCP sockets based transport. Netty SSL is similar to Netty TCP but
it provides enhanced security by encrypting TCP connections using the Secure Sockets Layer (SSL).
Warning
Use of SSLv3 protocol in SSL connectors/acceptors was disallowed because of " Poodle"
vulnerability. JMS clients connecting by this protocol will be refused.
The following example shows Netty configuration for one way SSL:
Note
Most of the following parameters can be used with acceptors as well as connectors. However
some parameters work only with acceptors. The parameter description explains the difference
between using these parameters in connectors and acceptors.
<acceptors>
<param key="ssl-enabled" value="true"/>
<param key="key-store-password" value="[keystore password]"/>
<param key="key-store-path" value="[path to keystore file]"/>
</netty-acceptor>
</acceptors>
T ab le 18.2. N et t y SSL C o n f ig u rat io n Pro p ert ies
4 21
T ab le 18.2. N et t y SSL C o n f ig u rat io n Pro p ert ies

Pro p ert y N ame
D ef au lt
D escrip t io n
ssl-enabled
key-store-password
true
[keystore password]
This enables SSL

When used on an acceptor this
is the password for the server
side keystore.
When used on a connector this
is the password for the clientside keystore. This is only
relevant for a connector if you
are using two way SSL (mutual
authentication). This value can
be configured on the server, but
it is downloaded and used by
the client.
key-store-path
[path to keystore file]
When used on an acceptor this

is the path to the SSL key store
on the server which holds the
server's certificates (whether
self-signed or signed by an
authority).
When used on a connector this
is the path to the client-side
SSL key store which holds the
client certificates. This is only
relevant for a connector if you
are using 2-way SSL (i.e.
mutual authentication).
Although this value is
configured on the server, it is
downloaded and used by the
client.
If you are configuring Netty for two way SSL (mutual authentication between server and client), there
are three additional parameters in addition to the ones described in the above example for one way
SSL:
need-client-auth: This specifies the need for two way (mutual authentication) for client
connections.
trust-store-password: When used on an acceptor this is the password for the server side
trust store. When used on a connector this is the password for the client side trust store. This is
relevant for a connector for both one way and two way SSL. This value can be configured on the
server, but it is downloaded and used by the client
trust-store-path: When used on an acceptor this is the path to the server side SSL trust store
that holds the keys of all the clients that the server trusts. When used on a connector this is the
path to the client side SSL key store which holds the public keys of all the servers that the client
trusts. This is relevant for a connector for both one way and two way SSL. This path can be
configured on the server, but it is downloaded and used by the client.
Report a bug
18.2.4 . Configuring Net t y HT T P
4 22
18.2.4 . Configuring Net t y HT T P

Netty HTTP tunnels packets over the HTTP protocol. It can be useful in scenarios where firewalls
allow only HTTP traffic to pass. Netty HTTP uses the same properties as Netty TCP along with some
following additional properties:
Note
The following parameters can be used with acceptors as well as connectors. Netty HTTP
transport does not allow the reuse of standard HTTP port (8080 by default). The use of
standard HTTP port results in an exception. You can use Section 18.2.5, Configuring Netty
Servlet (Netty Servlet Transport) for tunneling HornetQ connections through standard HTTP
port.
<socket-binding name="messaging-http" port="7080" />

<acceptors>
<netty-acceptor name="netty" socket-binding="messaging-http">
<param key="http-enabled" value="false"/>
<param key="http-client-idle-time" value="500"/>
<param key="http-client-idle-scan-period" value="500"/>
<param key="http-response-time" value="10000"/>
<param key="http-server-scan-period" value="5000"/>
<param key="http-requires-session-id" value="false"/>
</netty-acceptor>
</acceptors>
The following table describes the additional properties for configuring Netty HTTP:
T ab le 18.3. N et t y H T T P C o n f ig u rat io n Pro p ert ies
Pro p ert y N ame
D ef au lt
D escrip t io n
http-enabled
http-client-idle-time
false
500 milliseconds
http-client-idle-scan-period
500 milliseconds
http-response-time
10000 milliseconds
http-server-scan-period
5000 milliseconds
http-requires-session-id
false
If this is true HTTP is enabled

How long a client can be idle
before sending an empty HTTP
request to keep the connection
alive
How often (milliseconds) to
scan for idle clients
The time period for which the
server can wait before sending
an empty HTTP response to
keep the connection alive
How often, in milliseconds, to
scan for clients needing
responses
If this is true then client will wait
after the first call to receive a
session ID
4 23
Warning
Automatic client failover is not supported for clients connecting through Netty HTTP transport.
Report a bug
18.2.5. Configuring Net t y Servlet

The servlet transport allows HornetQ traffic to be tunneled over HTTP to a servlet running in a servlet
engine which then redirects it to an in-VM HornetQ server. Netty HTTP transport acts as a web server
listening for HTTP traffic on specific ports. With the servlet transport HornetQ traffic is proxied
through a servlet engine which may already be serving web site or other applications.
In order to configure a servlet engine to work the Netty Servlet transport you need to follow these
steps:
D eploy the servlet: The following example describes a web application that uses the servlet:
<web-app>
<servlet>
<servlet-name>HornetQServlet</servlet-name>
<servletclass>org.jboss.netty.channel.socket.http.HttpTunnelingServlet</servlet
-class>
<init-param>
<param-name>endpoint</param-name>
<param-value>local:org.hornetq</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>HornetQServlet</servlet-name>
<url-pattern>/HornetQServlet</url-pattern>
</servlet-mapping>
</web-app>
The init parameter endpoint specifies the host attribute of the Netty acceptor that the servlet will
forward its packets to
Insert the Netty servlet acceptor on the server side configuration: The following example shows the
definition of an acceptor in server configuration files (stand al o ne. xml and d o mai n. xml ):
<acceptors>
<acceptor name="netty-servlet">
<factory-class>
org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory
</factory-class>
<param key="use-servlet" value="true"/>
<param key="host" value="org.hornetq"/>
</acceptor>
</acceptors>
4 24
The last step is to define a connector for the client in server configuration files
(stand al o ne. xml and d o mai n. xml ):
<netty-connector name="netty-servlet" socket-binding="http">
<param key="servlet-path" value="/messaging/HornetQServlet"/>
</netty-connector>
It is also possible to use the servlet transport over SSL by adding the following configuration to
the connector:
<netty-connector name="netty-servlet" socket-binding="https">
<param key="servlet-path" value="/messaging/HornetQServlet"/>
<param key="ssl-enabled" value="true"/>
<param key="key-store-path" value="path to a key-store"/>
<param key="key-store-password" value="key-store password"/>
</netty-connector>
Warning
Automatic client failover is not supported for clients connecting through HTTP tunneling
servlet.
Note
Netty servlet cannot be used to configure EAP 6 servers in order to set up a HornetQ cluster.
Report a bug
18.3. Dead Connect ion Det ect ion

18.3.1. Closing Dead Connect ion Resources on t he Server
A HornetQ core or JMS client application must close its resources before it exits. You can configure
your application to automatically close its resources by using the fi nal l y block in the
application's code.
The following example shows a core client application which closes its session and session factory
in a fi nal l y block:
ServerLocator locator = null;
ClientSessionFactory sf = null;
ClientSession session = null;
try
{
locator = HornetQClient.createServerLocatorWithoutHA(..);
4 25
sf = locator.createClientSessionFactory();;
session = sf.createSession(...);
... do some operations with the session...
}
finally
{
if (session != null)
{
session.close();
}
if (sf != null)
{
sf.close();
}
if(locator != null)
{
locator.close();
}
}
The following example shows a JMS client application which closes its session and session factory
in a fi nal l y block:
Connection jmsConnection = null;
try
{
ConnectionFactory jmsConnectionFactory =
HornetQJMSClient.createConnectionFactoryWithoutHA(...);
jmsConnection = jmsConnectionFactory.createConnection();
... do some operations with the connection...
}
finally
{
if (connection != null)
{
connection.close();
}
}
U sin g C o n n ect io n T ime t o Live ( T T L) Paramet er
The connection-ttl parameter determines the time period for which the server keeps the
connection alive when it does not receive data or ping packets from the client. This parameter
ensures that dead server resources like old sessions are sustained longer thereby allowing clients to
reconnect when a failed network connection recovers.
4 26
You can define connection TTL for JMS clients by specifying connection-ttl parameter in
Ho rnetQ C o nnecti o nFacto ry instance. If you are deploying JMS connection factory instances
direct into JND I; you can define connection-ttl parameter in stand al o ne. xml and
d o mai n. xml server configuration files.
The default value of connection-ttl parameter is 60000 milliseconds. If you do not need clients to
specify their own connection TTL; you can define the connection-ttl-override parameter in
server configuration files to override all values. The connection-ttl-override parameter is
disabled by default and has a value of -1.
G arb ag e C o llect io n
HornetQ uses garbage collection to detect and close the sessions which are not explicitly closed in a
fi nal l y block. HornetQ server logs a warning similar to the warning shown below before closing
the sessions:
[Finalizer] 20:14:43,244 WARNING
[org.hornetq.core.client.impl.DelegatingSession] I'm closing a
ClientSession you left open. Please make sure you close all
ClientSessions explicitly before let
ting them go out of scope!
[Finalizer] 20:14:43,244 WARNING
[org.hornetq.core.client.impl.DelegatingSession] The session you didn't
close was created here:
java.lang.Exception
at
org.hornetq.core.client.impl.DelegatingSession.<init>(DelegatingSession.j
ava:83)
at org.acme.yourproject.YourClass (YourClass.java:666)
The log message contains information about the code part where a JMS connection or user session
was created and not closed later.
Report a bug
18.3.2. Det ect ing Client Side Failure

The client application automatically sends ping packets to the server to prevent the client from
shutting down. In a similar way, the client application considers the connection alive as long as it
receives data from the server.
If the client does not receive data packets from the server for a time period specified by clientfailure-check-period parameter then the client considers that the connection has failed. The
client then initiates a failover or calls Fai l ureLi stener instances.
For JMS clients, client failure check period is configured using ClientFailureCheckPeriod
attribute on Ho rnetQ C o nnecti o nFacto ry instance. If you are deploying JMS connection factory
instances directly into JND I on the server side, you can specify client-failure-check-period
parameter in stand al o ne. xml and d o mai n. xml server configuration files.
The default value for client failure check period is 3000 milliseconds. A value of -1 means that the
client will never close the connection if no data is received from the server. The value of client failure
check period is much lower than connection TTL so that clients can reconnect in case of a transition
failure.
C o n f ig u rin g Asyn ch ro n o u s C o n n ect io n Execu t io n
4 27
By default, packets received on the server side are executed on the remoting thread. It is possible to
free up the remoting thread by processing operations asynchronously on any thread from the thread
pool. You can configure asynchronous connection execution using async-connectionexecution-enabled parameter in stand al o ne. xml and d o mai n. xml server configuration files.
The default value of this parameter is " true" .
Note
If you process operations asynchronously on any thread from the thread pool, it adds a little
latency. Short running operations are always handled on the remoting thread for performance
reasons.
Report a bug
18.4 . Work wit h Large Messages

18.4 .1. Work wit h Large Messages
HornetQ supports the use of large messages even when either the client or server has limited
amounts of memory. Large messages can be streamed as they are, or compressed further for more
efficient transferral. A user can send a large message by setting an InputStream in the body of the
message. When the message is sent HornetQ reads this InputStream and transmits data to the
server in fragments.
The client or the server never store the complete body of a large message in memory. The consumer
initially receives a large message with an empty body and thereafter sets an O utputStream on the
message to stream it in fragments to a disk file.
Report a bug
18.4 .2. Configuring Hornet Q Large Messages

C o n f ig u rin g t h e Server
In Standalone mode large messages are stored in
EAP _HO ME/stand al o ne/d ata/l arg emessag es directory. In D omain mode large messages are
stored in EAP _HO ME/d o mai n/servers/SER VER NAME/d ata/l arg emessag es directory. The
configuration property l arg e-messag es-d i recto ry indicates the location where large messages
are stored.
Important
To achieve best performance, we recommend storing the large messages directory on a
different physical volume to the message journal or the paging directory
Report a bug
18.4 .3. Configuring Paramet ers

You can configure HornetQ large messages by setting various parameters:
4 28
U sin g H o rn et Q C o re API o n C lien t Sid e

If you are using HornetQ Core API on client side you need to set
ServerLo cato r. setMi nLarg eMessag eSi ze parameter to specify minimum size of large
messages. The minimum size of large messages(min-large-message-size) is set to 100KiB
by default.
ServerLocator locator =
HornetQClient.createServerLocatorWithoutHA(new
TransportConfiguration(NettyConnectorFactory.class.getName()))
locator.setMinLargeMessageSize(25 * 1024);
ClientSessionFactory factory =
HornetQClient.createClientSessionFactory();
C o n f ig u rin g server f o r Java Messag in g Service ( JMS) clien t s

If you using Java Messaging Service (JMS) you need to specify the minimum size of large
messages in the attribute mi n-l arg e-messag e-si ze of your server configuration files
(stand al o ne. xml and d o mai n. xml ). The minimum size of large messages(min-largemessage-size) is set to 100KiB by default.
Note
The value of the attribute mi n-l arg e-messag e-si ze should be in bytes
You may choose to compress large messages for fast and efficient transfer. All
compression/de-compression operations are handled on client side. If the compressed
message is smaller than mi n-l arg e-messag e-si ze,it is sent to the server as a regular
message. Using Java Messaging Service (JMS) you can compress large messages by
setting the boolean property co mpress-l arg e-messag es " true" on the server locator or
ConnectionFactory.
<connection-factory name="ConnectionFactory">
<connectors>
<connector-ref connector-name="netty"/>
</connectors>
...
<min-large-message-size>204800</min-large-message-size>
<compress-large-messages>true</compress-large-messages>
</connection-factory>
Report a bug
18.5. Paging
18.5.1. About Paging
4 29
HornetQ supports many message queues with each queue containing millions of messages. The
HornetQ server runs with limited memory thereby making it difficult to store all message queues in
memory at one time.
Paging is a mechanism used by the HornetQ server to transparently page messages in and out of
memory on need basis in order to accomodate large message queues in a limited memory.
HornetQ starts paging messages to disk, when the size of messages in memory for a particular
address exceeds the maximum configured message size.
Note
HornetQ paging is enabled by default.
Report a bug
18.5.2. Page Files

There is an individual folder for each address on the file system which stores messages in multiple
files. These files which store the messages are called page files. Each file contains messages up to
the maximum configured message size (pag e-si ze-bytes).
The system navigates the page files as needed and removes the page files as soon as all messages
in the page were received by client.
Note
If a consumer has a message selector to read messages from queue, only the messages in
memory that match the selector are delivered to the consumer. When the consumer
acknowledges delivery of these messages, new messages are depaged and loaded into
memory. For performance reasons, HornetQ does not scan paged messages to verify if they
match the consumer's message selector and there is no confirmation that new depaged
messages match the consumer's message selector. There may be messages that match
consumer's selector on disk in page files but HornetQ does not load them into memory until
another consumer reads the messages in memory and provides free space. If the free space is
not available, the consumer with selector may not receive any new messages.
Report a bug
18.5.3. Configurat ion of Paging Folder

Global paging parameters are specified in server configuration files (standalone.xml and
domain.xml). You can configure the location of the paging directory/folder by using the pagingdirectory parameter:
<hornetq-server>
...
<paging-directory>/location/paging-directory</paging-directory>
...
</hornetq-server>
4 30
The paging-directory parameter is used to specify a location/folder to store the page files.
HornetQ creates one folder for each paging address in this paging directory. The page files are
stored in these folders.
The default paging directory is EAP _HO ME/stand al o ne/d ata/messag i ng pag i ng (standalone
mode) and EAP _HO ME/d o mai n/servers/SER VER NAME/d ata/messag i ng pag i ng (domain
mode).
Report a bug
18.5.4 . Paging Mode

When messages delivered to an address exceed the configured size, that address goes into
" page/paging mode" .
Note
Paging is done individually per address. If you configure a max-size-bytes for an address,
it means each matching address will have a maximum size that you specified. However it does
not mean that the total overall size of all matching addresses is limited to max-size-bytes.
Even with page mode, the server may crash due to an out-of-memory error. HornetQ keeps a
reference to each page file on the disk. In a situation with millions of page files, HornetQ can
face memory exhaustion. To minimize this risk, it is important to set the attribute page-sizebytes to a suitable value. You must configure the memory for your JBoss EAP 6 server higher
than (number of destinations)*(max-size-bytes), otherwise an out-of-memory error
can occur.
You can configure the maximum size in bytes (max-size-bytes) for an address in server
configuration files (stand al o ne. xml and d o mai n. xml ):
<address-settings>
<address-setting match="jms.someaddress">
<max-size-bytes>104857600</max-size-bytes>
<page-size-bytes>10485760</page-size-bytes>
<address-full-policy>PAGE</address-full-policy>
</address-setting>
</address-settings>
The following table describes the parameters on the address settings:
T ab le 18.4 . Pag in g Ad d ress Set t in g s
Elemen t
D ef au lt
Valu e
D escrip t io n
max-sizebytes
page-sizebytes
10485760
This is used to specify the maximum memory size the address can
have before entering nto paging mode
This is used to specify the size of each page file used on the paging
system.
2097152
4 31
Elemen t
D ef au lt
Valu e
D escrip t io n
addressfull-policy
PAGE
page-maxcache-size
This value of this attribute is used for paging decisions. You can set
either of these values for this attribute: P AG E: To enable paging and
page messages beyond the set limit to disk, D R O P : To silently drop
messages which exceed the set limit, FAIL: To drop messages and
send an exception to client message producers, BLO C K: To block
client message producers when they send messages beyond the set
limit
The system will keep page files up to page-max-cache-size in
memory to optimize Input/Output during paging navigation
Important
If you don't want to page messages when the maximum size is reached, you may choose to
configure an address in order to simply drop messages, drop messages with an exception on
client side or block producers from sending further messages, by setting the address-fullpolicy to D R O P , FAIL and BLO C K respectively. In the default configuration, all addresses
are configured to page messages after an address reaches max-size-bytes.
Ad d resses wit h Mu lt ip le Q u eu es
When a message is routed to an address that has multiplte queues bound to it, there is only a single
copy of the message in memory. Each queue only handles a reference to this original copy of the
message. Thus the memory is freed up only when all the queues referencing the original message,
have delivered the message.
Note
A single lazy queue/subscription can reduce the Input/Output performance of the entire
address as all the queues will have messages being sent through an extra storage on the
paging system.
Report a bug
18.6. Divert s
D iverts are objects configured in HornetQ; which help in diverting messages from one address (to
which the message is routed) to some other address. D iverts can be configured in server
configuration files (stand al o ne. xml and d o mai n. xml ).
D iverts can be classified into the following types:
Exclusive D ivert: A message is only diverted to a new address and not sent to the old address at
all
Non-exclusive D ivert: A message continues to go the old address, and a copy of it is also sent to
the new address. Non-exclusive diverts can be used for splitting the flow of messages
4 32
D iverts can be configured to apply a T ransfo rmer and an optional message filter. An optional
message filter helps only divert messages which match the specified filter. A transformer is used for
transforming messages to another form. When a transformer is specified; all diverted messages are
transformed by the T ransfo rmer.
A divert only diverts a message to an address within the same server. If you need to divert a message
to an address on a different server, you can follow the pattern described below:
D ivert messages to a local store and forward queue. Setup a bridge which consumes from that
queue and directs messages to an address on a different server
You can combine diverts with bridges to create various routings.
Report a bug
18.6.1. Exclusive Divert

An exclusive divert; diverts all messages from an old address to a new address. Matching messages
are not routed to the old address at all. You can enable exclusive divert by setting exclusive
attribute as true in stand al o ne. xml and d o mai n. xml server configuration files.
The following example shows an exclusive divert configured in server configuration file(s):
<divert name="prices-divert">
<address>jms.topic.priceUpdates</address>
<forwarding-address>jms.queue.priceForwarding</forwarding-address>
<filter string="office='New York'"/>
<transformer-class-name>
org.hornetq.jms.example.AddForwardingTimeTransformer
</transformer-class-name>
<exclusive>true</exclusive>
</divert>
The following list describes the attributes used in the above example:
address: Messages sent to this address are diverted to another address
forwarding-address: Messages are diverted to this address from the old address
filter-string: Messages which match the filter-string value are diverted. All other
messages are routed to the normal address
transformer-class-name: If you specify this parameter; it executes transformation for each
matching message. This allows you to change a message's body or property before it is diverted
exclusive: Used to enable or disable exclusive divert
Report a bug
18.6.2. Non-exclusive Divert

Non-exclusive diverts forward a copy of the original message to the new address. The original
message continues to arrive at the old address. You can configure non-exclusive diverts by setting
exclusive property as false in stand al o ne. xml and d o mai n. xml server configuration files.
The following example shows a non-exclusive divert:
4 33
<divert name="order-divert">
<address>jms.queue.orders</address>
<forwarding-address>jms.topic.spyTopic</forwarding-address>
<exclusive>false</exclusive>
</divert>
The above example makes a copy of every message sent to jms.queue.orders address and sends
it to jms.topic.spyTopic address.
Report a bug
18.7. T he Client Classpat h

HornetQ requires several jars on the Client Classpath depending on whether the client uses HornetQ
Core API, JMS, or JND I.
Warning
All the jars mentioned here can be found in the EAP_HOME/bi n/cl i ent directory of the
HornetQ distribution. Be sure you only use the jars from the correct version of the release, you
must not mix and match versions of jars from different HornetQ versions. Mixing and matching
different jar versions may cause subtle errors and failures to occur.
To set the client classpath, include EAP_HOME/bi n/cl i ent/jbo ss-cl i ent. jar. You can also
use Maven dependency settings as described in the EAP _HO ME/bi n/cl i ent/R EAD ME-EJBJMS. txt.
Report a bug
18.8. Configurat ion

18.8.1. Configure t he JMS Server
To configure the JMS Server for HornetQ, edit the server configuration file. The server configuration is
contained in the EAP_HOME/d o mai n/co nfi g urati o n/d o mai n. xml file for domain servers, or in
the EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne-ful l . xml file for standalone
servers.
The <subsystem xml ns= "urn: jbo ss: d o mai n: messag i ng : 1. 4 "> element in the server
configuration file contains all JMS configuration. Add any JMS C o nnecti o nFacto ry, Q ueue, or
T o pi c instances required for the JND I.
1. En ab le t h e JMS su b syst em in JB o ss EAP 6 .
Within the <extensi o ns> element, verify that the following line is present and is not
commented out:
<extension module="org.jboss.as.messaging"/>
2. Ad d t h e b asic JMS su b syst em.
4 34
If the Messaging subsystem is not present in your configuration file, add it.
a. Look for the <pro fi l e> which corresponds to the profile you use, and locate its
<subsystems> tag.
b. Paste the following XML immediately following the <pro fi l e> tag.
<subsystem xmlns="urn:jboss:domain:messaging:1.4">
<hornetq-server>

</hornetq-server>
</subsystem>
All further configuration will be added to the empty line above.
3. Ad d b asic co n f ig u rat io n f o r JMS.
Add the following XML in the blank line after the <subsystem
xml ns= "urn: jbo ss: d o mai n: messag i ng : 1. 4 "><ho rnetq -server> tag:
<journal-min-files>2</journal-min-files>
<journal-type>NIO</journal-type>
<persistence-enabled>true</persistence-enabled>
Customize the values above to meet your needs.
Warning
The value of jo urnal -fi l e-si ze must be higher than or equal to mi n-l arg emessag e-si ze (100KiB by default), or the server won't be able to store the message.
4. Ad d co n n ect io n f act o ry in st an ces t o H o rn et Q

The client uses a JMS C o nnecti o nFacto ry object to make connections to the server. To
add a JMS connection factory object to HornetQ, include a single <jms-co nnecti o nfacto ri es> tag and <co nnecti o n-facto ry> element for each connection factory as
follows:
<jms-connection-factories>
<connection-factory name="InVmConnectionFactory">
<connectors>
<connector-ref connector-name="in-vm"/>
</connectors>
<entries>
<entry name="java:/ConnectionFactory"/>
</entries>
<connection-factory name="RemoteConnectionFactory">
<connectors>
</connectors>
<entries>
<entry
4 35
name="java:jboss/exported/jms/RemoteConnectionFactory"/>
</entries>
<pooled-connection-factory name="hornetq-ra">
<transaction mode="xa"/>
<connectors>
</connectors>
<entries>
<entry name="java:/JmsXA"/>
</entries>
</pooled-connection-factory>
</jms-connection-factories>
5. C o n f ig u re t h e netty co n n ect o rs an d accep t o rs
This JMS connection factory uses netty acceptors and connectors. These are references to
connector and acceptor objects deployed in the server configuration file. The connector
object defines the transport and parameters used to connect to the HornetQ server. The
acceptor object identifies the type of connections accepted by the HornetQ server.
To configure the netty connectors, include the following settings:
<connectors>
<netty-connector name="netty" socket-binding="messaging"/>
<netty-connector name="netty-throughput" socketbinding="messaging-throughput">
</netty-connector>
</connectors>
To configure the netty acceptors, include the following settings:
<acceptors>
<netty-acceptor name="netty-throughput" socketbinding="messaging-throughput">
</netty-acceptor>
</acceptors>
6. R eview t h e co n f ig u rat io n
If you have followed the previous steps, your messaging subsystem should look like the
following:
<hornetq-server>
<journal-min-files>2</journal-min-files>
<journal-type>NIO</journal-type>
<persistence-enabled>true</persistence-enabled>
<jms-connection-factories>
4 36
<connection-factory name="InVmConnectionFactory">
<connectors>
</connectors>
<entries>
<entry name="java:/ConnectionFactory"/>
</entries>
<connection-factory name="RemoteConnectionFactory">
<connectors>
</connectors>
<entries>
<entry
name="java:jboss/exported/jms/RemoteConnectionFactory"/>
</entries>
<pooled-connection-factory name="hornetq-ra">
<connectors>
</connectors>
<entries>
<entry name="java:/JmsXA"/>
</entries>
</jms-connection-factories>
<connectors>
<netty-connector name="netty" socketbinding="messaging"/>
<netty-connector name="netty-throughput" socketbinding="messaging-throughput">
</netty-connector>
</connectors>
<acceptors>
<netty-acceptor name="netty" socketbinding="messaging"/>
<netty-acceptor name="netty-throughput" socketbinding="messaging-throughput">
</netty-acceptor>
</acceptors>
</hornetq-server>
</subsystem>
7. C o n f ig u re t h e so cket b in d in g g ro u p s
The netty connectors reference the messag i ng and messag i ng -thro ug hput socket
bindings. The messag i ng socket binding uses port 5445, and the messag i ng thro ug hput socket binding uses port 5455. The <so cket-bi nd i ng -g ro up> tag is in a
separate section of the server configuration file. Ensure the following socket bindings are
present in the <so cket-bi nd i ng -g ro ups> element:
4 37
<socket-binding-group name="standard-sockets" defaultinterface="public" port-offset="${jboss.socket.binding.portoffset:0}">

...
...
8. Ad d q u eu e in st an ces t o H o rn et Q
There are 4 ways to setup the queue instances (or JMS destinations) for HornetQ.
Use the Management Console
To use the Management Console, the server must have been started in the Messag eEnabl ed mode. You can do this by using the -c option and forcing the use of the
stand al o ne-ful l . xml (for standalone servers) configuration file. For example, in the
standalone mode, the following will start the server in a message enabled mode
./standalone.sh -c standalone-full.xml
Once the server has started, logon to the Management Console and select the
C o n f ig u rat io n tab. Expand the Su b syst ems menu, then expand the Messag in g menu
and click D est in at io n s. Next to D efaul t on the JMS Messaging Provider table, click
Vi ew, and then click Ad d to enter details of the JMS destination.
Use the Management CLI:
First, connect to the Management CLI:
bin/jboss-cli.sh --connect
Next, change into the messaging subsystem:
cd /subsystem=messaging/hornetq-server=default
Finally, execute an add operation, replacing the examples values given below with your
own:
./jms-queue=testQueue:add(durable=false,entries=
["java:jboss/exported/jms/queue/test"])
Create a JMS configuration file and add it to the deployments folder
Start by creating a JMS configuration file: example-jms.xml. Add the following entries to it,
replacing the values with your own:
<messagingdeployment xmlns="urn:jboss:messaging-deployment:1.0">
<hornetq-server>
<jms-destinations>
<jms-queue name="testQueue">
<entry name="queue/test"/>
<entry
4 38
name="java:jboss/exported/jms/queue/test"/>
</jms-queue>
<jms-topic name="testTopic">
<entry name="topic/test"/>
<entry
name="java:jboss/exported/jms/topic/test"/>
</jms-topic>
</jms-destinations>
</hornetq-server>
</messaging-deployment>
Save this file in the deployments folder and do a deployment.
Add entries in the JBoss EAP 6 configuration file.
Queue attributes can be set in one of two ways.
Configuration at a JMS level
The following shows a queue predefined in the stand al o ne. xml or d o mai n. xml
configuration file.
<jms-queue name="selectorQueue">
<entry name="/queue/selectorQueue"/>
<selector string="color='red'"/>
<durable>true</durable>
</jms-queue>
This name attribute of queue defines the name of the queue. When we do this at a jms
level we follow a naming convention so the actual name of the core queue will be
jms. q ueue. sel ecto rQ ueue.
The entry element configures the name that will be used to bind the queue to JND I. This
is a mandatory element and the queue can contain multiple of these to bind the same
queue to different names.
The selector element defines what JMS message selector the predefined queue will
have. Only messages that match the selector will be added to the queue. This is an
optional element with a default of null when omitted.
The durable element specifies whether the queue will be persisted. This again is
optional and defaults to true if omitted.
Configuration at a core level
A queue can be predefined at a core level in the stand al o ne. xml or d o mai n. xml
file. For example:
<core-queues>
<queue name="jms.queue.selectorQueue">
<address>jms.queue.selectorQueue</address>
<filter string="color='red'"/>
<durable>true</durable>
</queue>
</core-queues>
9. Perf o rm ad d it io n al co n f ig u rat io n
4 39
If you need additional settings, review the D TD in EAP_HOME/d o cs/schema/jbo ss-asmessag i ng _1_4 . xsd .
Report a bug
18.8.2. Configure JMS Address Set t ings

The JMS subsystem has several configurable options which control aspects of how and when a
message is delivered, how many attempts should be made, and when the message expires. These
configuration options all exist within the <ad d ress-setti ng s> configuration element.
A common feature of address configurations is the syntax for matching multiple addresses, also
known as wild cards.
Wild card Syn t ax
Address wildcards can be used to match multiple similar addresses with a single statement, similar to
how many systems use the asterisk ( *) character to match multiple files or strings with a single
search. The following characters have special significance in a wildcard statement.
T ab le 18.5. JMS Wild card Syn t ax
C h aract er
D escrip t io n
. (a single period)
D enotes the space between words in a wildcard

expression.
Matches any sequence of zero or more words.
Matches a single word.
# (a pound or hash symbol)

* (an asterisk)
T ab le 18.6 . JMS Wild card Examp les
Examp le
D escrip t io n
news.europe.#
Matches news. euro pe, news. euro pe. spo rt,

news. euro pe. po l i ti c, but not news. usa or
euro pe.
Matches news. euro pe but not
news. euro pe. spo rt.
Matches news. euro pe. spo rt and
news. usa. spo rt, but not
news. euro pe. po l i ti cs.
news.*
news.*.sport
Examp le 18.2. D ef au lt Ad d ress Set t in g C o n f ig u rat io n

The values in this example are used to illustrate the rest of this topic.
<address-settings>

<address-setting match="#">
<dead-letter-address>jms.queue.DLQ</dead-letter-address>
<expiry-address>jms.queue.ExpiryQueue</expiry-address>
<redelivery-delay>0</redelivery-delay>
<max-size-bytes>10485760</max-size-bytes>
<address-full-policy>BLOCK</address-full-policy>
440
<message-counter-history-day-limit>10</message-counter-historyday-limit>
</address-setting>
</address-settings>
T ab le 18.7. D escrip t io n o f JMS Ad d ress Set t in g s

Elemen t
D escrip t io n
D ef au lt Valu e
T yp e
ad d ress-ful l po l i cy
D etermines what
happens when an
address where maxsize-bytes is specified
becomes full.
If a dead letter address
is specified, messages
are moved to the dead
letter address if maxd el i very-attempts
delivery attempts have
failed. Otherwise, these
undelivered messages
are discarded.
Wildcards are allowed.
If the expiry address is
present, expired
messages are sent to
the address or
addresses matched by
it, instead of being
discarded. Wildcards
are allowed.
D efines whether a
queue only uses last
values or not.
The maximum number
of times to attempt to
re-deliver a message
before it is sent to
d ead -l etterad d ress or
discarded.
The maximum bytes
size.
D ay limit for the
message counter
history.
The number of page
files to keep in memory
to optimize IO during
paging navigation.
The paging size.
PAGE
STRING
jms.queue.D LQ
STRING
jms.queue.ExpiryQueu
e
STRING
false
BOOLEAN
10
INT
10485760L
LONG
10
INT
INT
INT
d ead -l etterad d ress
expi ry-ad d ress
l ast-val ue-q ueue
max-d el i veryattempts
max-si ze-bytes
messag e-co unterhi sto ry-d ayl i mi t
pag e-max-cachesi ze
pag e-si ze-bytes
441
Elemen t
D escrip t io n
D ef au lt Valu e
T yp e
red el i very-d el ay
Time to delay between

re-delivery attempts of
messages, expressed
in milliseconds. If set to
0 , re-delivery attempts
occur indefinitely.
D efines how long to
wait when the last
consumer is closed on
a queue before
redistributing any
messages.
A parameter for an
address that sets the
condition of a
message not routed to
any queues to instead
be sent the to the dead
letter address (D LA)
indicated for that
address.
The minimum rate of
message consumption
allowed before a
consumer is
considered " slow."
Measured in
messages-per-second.
What should happen
when a slow consumer
is detected. KILL will
kill the consumer's
connection (which will
obviously impact any
other client threads
using that same
connection). NO T IFY
will send a
CONSUMER_SLOW
management
notification which an
application could
receive and take action
with.
How often to check for
slow consumers on a
particular queue.
Measured in seconds.
0L
LONG
-1L
LONG
false
BOOLEAN
-1
INT
red i stri buti o nd el ay
send -to -d l a-o nno -ro ute
sl o w-co nsumerthresho l d
sl o w-co nsumerpo l i cy
sl o w-co nsumercheck-peri o d
STRING
INT
C o n f ig u re Ad d ress Set t in g an d Pat t ern At t rib u t es

Choose either the Management CLI or the Management Console to configure your pattern
attributes as required.
442
A. C o n f ig u re t h e Ad d ress Set t in g s U sin g t h e Man ag emen t C LI

Use the Management CLI to configure address settings.
a. Ad d a N ew Pat t ern
Use the ad d 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 pattern titled patternname, with a max-d el i very-attempts
attribute declared as 5. The examples for both Standalone Server and a Managed
D omain editing on the ful l profile are shown.
[standalone@ localhost:9999 /] /subsystem=messaging/hornetqserver=default/address-setting=patternname/:add(max-deliveryattempts=5)
[domain@ localhost:9999 /]
/profile=full/subsystem=messaging/hornetqserver=default/address-setting=patternname/:add(max-deliveryattempts=5)
b. Ed it Pat t ern At t rib u t es
Use the wri te 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 max-d el i very-attempts
value to 10
[standalone@ localhost:9999 /] /subsystem=messaging/hornetqserver=default/address-setting=patternname/:writeattribute(name=max-delivery-attempts,value=10)
/profile=full/subsystem=messaging/hornetqserver=default/address-setting=patternname/:writeattribute(name=max-delivery-attempts,value=10)
c. C o n f irm Pat t ern At t rib u t es
model.
[standalone@ localhost:9999 /] /subsystem=messaging/hornetqserver=default/address-setting=patternname/:read-resource
/profile=full/subsystem=messaging/hornetqserver=default/address-setting=patternname/:read-resource
B. C o n f ig u re t h e Ad d ress Set t in g s U sin g t h e Man ag emen t C o n so le
Use the Management Console to configure address settings.
443
a. Log into the Management Console of your Managed D omain or Standalone Server.
b. Select the C o nfi g urati o n tab at the top of the screen. For D omain mode, select a
profile from the P ro fi l e menu at the top left. Only the ful l and ful l -ha profiles
have the messag i ng subsystem enabled.
c. Expand the Messag i ng menu, and select D esti nati o ns.
d. A list of JMS Providers is shown. In the default configuration, only one provider, called
d efaul t, is shown. Click Vi ew to view the detailed settings for this provider.
e. Click the Ad d ress Setti ng s tab. Either add a new pattern by clicking Ad d , or select
an existing pattern and clickEd i t to update the settings.
f. If you are adding a new pattern, the P attern field refers to the match parameter of the
ad d ress-setti ng element. You can also edit the D ead Letter Ad d ress, Expi ry
Ad d ress, R ed el i very D el ay, and Max D el i very Attempts. Other options need
to be configured using the Management CLI.
Report a bug
18.8.3. T emporary Queues and Runt ime Queues

While designing request-reply scenarios that involve a client sending a request and waiting for a
reply, an addressable issue is whether each runtime instance of the client has a dedicated queue for
its replies or whether the runtime instances access a shared queue, selecting their specific reply
message based on an appropriate attribute. If multiple queues are required, then we need the ability
to create a queue dynamically for use by the client, and JMS provides this facility using the concept
of temporary queues. The T empo raryQ ueue is created on request by the Q ueueSessi o n and exists
until it is deleted or for the life of the Q ueueC o nnecti o n (i.e. until the Q ueueC o nnecti o n is
closed). This means that although the T empo raryQ ueue is created by a specific Q ueueSessi o n, it
can be reused by any other Q ueueSessi o ns created from the same Q ueueC o nnecti o n to create a
Q ueueR ecei ver.
The tradeoff between having a shared queue for replies or having individual temporary queues is
influenced by the potential number of active client instances. With a shared-queue approach, at
some provider-specific threshold, contention for access to the queue can become a concern. This
has to be contrasted against the additional overhead associated with the provider creating queue
storage at runtime and the impact on machine memory of having to host a potentially large number of
temporary queues.
Note
The creation of temporary queues is accomplished with the createT empo raryQ ueue method.
Similarly, the creation of temporary topics is accomplished with the createT empo raryT o pi c
method. Both of these methods are for creating the physical queue and physical topic.
If there are messages that have been received but not acknowledged when a Q ueueSessi o n
terminates, these messages will be retained and redelivered when a consumer next accesses the
queue. A Q ueueSessi o n is used for creating Point-to-Point specific objects. In general, use the
Session object. The Q ueueSessi o n is used to support existing code. Using the Session object
simplifies the programming model, and allows transactions to be used across the two messaging
domains.
444
A T o pi cSessi o n is used for creating Pub/Sub specific objects. In general, use the Session object,
and use T o pi cSessi o n only to support existing code. Using the Session object simplifies the
programming model, and allows transactions to be used across the two messaging domains.
Report a bug
18.8.4 . Last -Value Queues

Last-Value queues are special queues which discard any messages when a newer message with the
same value for a well-defined Last-Value property is put in the queue. In other words, a Last-Value
queue only retains the last value. A typical example for Last-Value queue is for stock prices, where
you are only interested by the latest value for a particular stock.
C o n f ig u rin g Last - Valu e Q u eu es
Last-value queues are defined in the address-setting configuration:
<address-setting match="jms.queue.lastValueQueue">
<last-value-queue>true</last-value-queue>
</address-setting>
U sin g Last - Valu e Pro p ert y
The property name used to identify the last value is "_HQ _LVQ _NAME" (or the constant
Messag e. HD R _LAST _VALUE_NAME from the Core API). For example, if two messages with the same
value for the Last-Value property are sent to a Last-Value queue, only the latest message will be kept
in the queue:
Examp le 18.3. Sen d 1st messag e wit h Last - Valu e p ro p ert y set t o STOCK_NAME
TextMessage message = session.createTextMessage("1st message with LastValue property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
producer.send(message);
Examp le 18.4 . Sen d 2n d messag e wit h Last - Valu e p ro p ert y set t o STOCK_NAME
message = session.createTextMessage("2nd message with Last-Value
property set");
message.setStringProperty("_HQ_LVQ_NAME", "STOCK_NAME");
Examp le 18.5. O n ly t h e 2n d messag e will b e received ; it is t h e lat est wit h t h e Last Valu e p ro p ert y set :
TextMessage messageReceived =
(TextMessage)messageConsumer.receive(5000);
System.out.format("Received message: %s\n", messageReceived.getText());
Report a bug
445
18.8.5. Core and JMS Dest inat ions

HornetQ core does not have any concept of a JMS topic. A JMS topic is implemented in core as an
address (the topic name) with zero or more queues bound to it. Each queue bound to that address
represents a topic subscription. Likewise, a JMS queue is implemented as an address (the JMS
queue name) but with one single queue bound to it which represents the JMS queue.
A JMS topic is the channel through which users subscribe to receive specific messages from a
producer in the publish-and-subscribe model of JMS messaging.
A JMS queue is a channel through which users " pull" messages they want to receive using the Pointto-point (p2p) model, instead of automatically receiving messages on a particular topic. The
producer submits messages to the queue, and recipients can browse the queue and decide which
messages they wish to receive. In the p2p model, users can see the contents of the messages held in
the queue before deciding whether or not to accept their delivery.
If you want to configure settings for a JMS Queue with the name orders.europe, you need to configure
the corresponding core queue jms.queue.orders.europe:

<address-setting match="jms.queue.orders.europe">
<expiry-address>jms.queue.expiry.europe</expiry-address>
...
</address-setting>
Report a bug
18.8.6. JMS Message Select ors

If your messaging application needs to filter the messages it receives, you can use a JMS API
message selector, which allows a message consumer to specify the messages it is interested in.
Message selectors assign the work of filtering messages to the JMS provider rather than to the
application.
You can define your message selector as follows:
@ MessageDriven(name = "MDBMessageSelectorExample", activationConfig =
{
@ ActivationConfigProperty(propertyName = "destinationType",
propertyValue = "javax.jms.Queue"),
@ ActivationConfigProperty(propertyName = "destination", propertyValue
= "queue/testQueue"),
@ ActivationConfigProperty(propertyName = "messageSelector",
propertyValue = "color = 'RED'")
})
@ TransactionManagement(value= TransactionManagementType.CONTAINER)
@ TransactionAttribute(value= TransactionAttributeType.REQUIRED)
public class MDBMessageSelectorExample implements MessageListener
{
public void onMessage(Message message)....
}
Report a bug
18.8.7. Configure Messaging wit h Hornet Q
446
18.8.7. Configure Messaging wit h Hornet Q

The recommended method of configuring messaging in JBoss EAP 6 is in either the Management
Console or Management CLI. You can make persistent changes with either of these management
tools without needing to manually edit the stand al o ne. xml or d o mai n. xml configuration files. It
is useful however to familiarize yourself with the messaging components of the default configuration
files, where documentation examples using management tools give configuration file snippets for
reference.
Report a bug
18.8.8. Enable Logging for Hornet Q

You can enable logging for HornetQ in EAP 6.x using any of the following approaches:
Editing server configuration files (stand al o ne-ful l . xml and stand al o ne-ful l -ha. xml )
manually
Editing server configuration files using the CLI
Pro ced u re 18.1. Set H o rn et Q lo g g in g b y ed it in g server co n f ig u rat io n f iles man u ally
1. Open the server configuration file(s) for editing. For example stand al o ne-ful l . xml and
stand al o ne-ful l -ha. xml
2. Navigate to logging subsystem configuration in the file(s). The default configuration looks
like this:
<logger category="com.arjuna">
</logger>
...
<logger category="org.apache.tomcat.util.modeler">
<level name="WARN"/>
</logger>
....
3. Add the o rg . ho rnetq logger category along with the desired logging level as shown in the
following example:
<logger category="com.arjuna">
</logger>
...
<logger category="org.hornetq">
</logger>
....
R esu lt
HornetQ logging is enabled and log messages are processed based on the configured log level.
Set H o rn et Q lo g g in g b y ed it in g server co n f ig u rat io n f iles u sin g t h e C LI
447
You can also use CLI to add the o rg . ho rnetq logger category along with the desired logging level
to server configuration file(s). For more information see: Section 12.3.2, Configure a Log Category in
the CLI
Report a bug
18.8.9. Configuring Hornet Q Core Bridge

Examp le 18.6 . Examp le co n f ig u rat io n f o r H o rn et Q C o re B rid g e:
<bridges>
<bridge name="myBridge">
<queue-name>jms.queue.InQueue</queue-name>
<forwarding-address>jms.queue.OutQueue</forwarding-address>
<ha>true</ha>
<reconnect-attempts>-1</reconnect-attempts>
<use-duplicate-detection>true</use-duplicate-detection>
<static-connectors>
<connector-ref>
bridge-connector
</connector-ref>
</static-connectors>
</bridge>
</bridges>
T ab le 18.8. H o rn et Q C o re B rid g e At t rib u t es

At t rib u t e
D escrip t io n
name
All bridges must have a unique name on the

server.
This mandatory parameter is the unique name of
the local queue that the bridge consumes from.
The queue must already exist by the time the
bridge is instantiated at start-up.
This is the address on the target server that the
message will be forwarded to. If a forwarding
address is not specified, then the original
address of the message will be retained.
This optional parameter determines whether or
not this bridge should support high availability.
true means it will connect to any available
server in a cluster and support failover. The
default value is false.
This optional parameter determines the total
number of reconnect attempts the bridge should
make before giving up and shutting down. A
value of -1 signifies an unlimited number of
attempts. The default value is -1.
queue-name
forwarding-address
ha
reconnect-attempts
448
At t rib u t e
D escrip t io n
use-duplicate-detection
This optional parameter determines whether the

bridge will automatically insert a duplicate id
property into each message that it forwards.
The static-connectors is a list of connector-ref
elements pointing to connector elements defined
elsewhere. A connector encapsulates knowledge
of what transport to use (TCP, SSL, HTTP etc)
as well as the server connection parameters
(host, port etc).
static-connectors
Report a bug
18.8.10. Configuring JMS Bridge

HornetQ includes a fully functional JMS message bridge. The function of this bridge is to consume
messages from a source queue or topic, and send them to a target queue or topic, typically on a
different server.
The source and target servers do not have to be in the same cluster, which makes bridging suitable
for reliably sending messages from one cluster to another, for instance across a WAN, and where the
connection is unreliable.
A bridge can be deployed as a standalone application, with HornetQ standalone server or inside a
JBoss AS instance. The source and the target can be located in the same virtual machine or another
one.
Examp le 18.7. Examp le co n f ig u rat io n f o r JMS B rid g e:

<subsystem>
<hornetq-server>
...
</hornetq-server>
<jms-bridge name="myBridge">
<source>
<connection-factory name="ConnectionFactory"/>
<destination name="jms/queue/InQueue"/>
</source>
<target>
<connection-factory
name="jms/RemoteConnectionFactory"/>
<destination name="jms/queue/OutQueue"/>
<context>
<property key="java.naming.factory.initial"
value="org.jboss.naming.remote.client.InitialContextFactory"/>
<property key="java.naming.provider.url"
value="remote://192.168.40.1:4447"/>
</context>
</target>
<quality-of-service>AT_MOST_ONCE</quality-of-service>
<failure-retry-interval>1000</failure-retry-interval>
449
<max-retries>-1</max-retries>
<max-batch-size>10</max-batch-size>
<max-batch-time>100</max-batch-time>
<add-messageID-in-header>true</add-messageID-in-header>
</jms-bridge>
...
</subsystem>
Warning
It is recommended to use a connection factory that does not set the reco nnect-attempts
parameter (or sets it to 0 ), as JMS Bridge has its own max-retri es parameter to handle
reconnection. This is to avoid a potential collision that may result in longer reconnection
times.
T ab le 18.9 . H o rn et Q C o re JMS At t rib u t es

At t rib u t e
D escrip t io n
name
All bridges must have a unique name on the

server.
This injects the SourceCFF bean (also defined
in the beans file). This bean creates the source
ConnectionFactory.
This injects the SourceD estinationFactory bean
(also defined in the beans file). This bean
creates the source D estination.
This injects the TargetCFF bean (also defined in
the beans file). This bean creates the target
ConnectionFactory.
This injects the TargetD estinationFactory bean
(also defined in the beans file). This bean
creates the target D estination.
This parameter represents the required quality of
service mode. The possible values are:
AT_MOST_ONCE, D UPLICATES_OK,
ONCE_AND _ONLY_ONCE
This represents the amount of time in
milliseconds to wait between trying to recreate
connections to the source or target servers when
the bridge has detected they have failed.
This represents the number of attempts to
recreate connections to the source or target
servers when the bridge has detected they have
failed. The bridge will give up after trying this
number of times. -1 represents 'try forever'.
This represents the maximum number of
messages to consume from the source
destination before sending them in a batch to
the target destination. Its value must >= 1.
source connection-factory
source destination name
target connection-factory
target destination name
quality-of-service
failure-retry-interval
max-retries
max-batch-size
4 50
At t rib u t e
D escrip t io n
max-batch-time
This represents the maximum number of

milliseconds to wait before sending a batch to
target, even if the number of messages
consumed has not reached MaxBatchSize. Its
value must be -1 to represent 'wait forever', or >=
1 to specify an actual time.
If true, then the original message's message id
will be appended in the message sent to the
destination in the header
HORNETQ_BRID GE_MSG_ID _LIST. If the
message is bridged more than once, each
message id will be appended. This enables a
distributed request-response pattern to be used.
add-messageID -in-header
When you receive the message you can send a

response using the correlation id of the first
message id, so when the original sender
receives the message, it is easy to correlate.
Note
When shutting down a server that has a deployed JMS bridge with quality-of-service
attribute set to O NC E_AND _O NLY _O NC E, shut the server down with the JMS bridge first to
avoid unexpected exceptions.
For more complete instructions, see Section 18.13.2, Create a JMS Bridge .
Report a bug
18.8.11. Configure Delayed Redelivery

In t ro d u ct io n
D elayed redelivery is defined in the <red el i very-d el ay> element, which is a child element of the
<ad d ress-setti ng > configuration element in the Java Messaging Service (JMS) subsystem
configuration.

<address-setting match="jms.queue.exampleQueue">
<redelivery-delay>5000</redelivery-delay>
</address-setting>
If a redelivery delay is specified, the JMS system waits for the duration of this delay before
redelivering the messages. If <red el i very-d el ay> is set to 0 , there is no redelivery delay. Address
wildcards can be used on the match attribute of <ad d ress-match> element to configure the
redelivery delay for addresses that match the wildcard.
Report a bug
18.8.12. Configure Dead Let t er Addresses
4 51
In t ro d u ct io n
A dead letter address is defined in the <ad d ress-setti ng > element of the Java Messaging Service
(JMS) subsystem configuration.

<dead-letter-address>jms.queue.deadLetterQueue</dead-letter-address>
<max-delivery-attempts>3</max-delivery-attempts>
</address-setting>
If a <d ead -l etter-ad d ress> is not specified, messages are removed after trying to deliver <maxd el i very-attempts> times. By default, messages delivery is attempted 10 times. Setting <maxd el i very-attempts> to -1 allows infinite redelivery attempts. For example, a dead letter can be set
globally for a set of matching addresses and you can set <max-d el i very-attempts> to -1 for a
specific address setting to allow infinite redelivery attempts only for this address. Address wildcards
can also be used to configure dead letter settings for a set of addresses.
Report a bug
18.8.13. Configure Message Expiry Addresses

In t ro d u ct io n
Message expiry addresses are defined in the address-setting configuration of the Java Messaging
Service (JMS). For example:

<expiry-address>jms.queue.expiryQueue</expiry-address>
</address-setting>
If messages are expired and no expiry address is specified, messages are simply removed from the
queue and dropped. Address wildcards can also be used to configure specific ranges of an expiry
address for a set of addresses. See Section 18.8.2, Configure JMS Address Settings for the JMX
wildcard syntax and examples.
Report a bug
18.8.14 . Flow Cont rol

Flow control is used to limit the flow of data between a client and server, or a server and another
server, in order to prevent the client or the server being overloaded with data.
Consumer Flow Control - controls the flow of data between the server and the client as the client
consumes messages. For performance reasons clients normally buffer messages before
delivering to the consumer via the recei ve() method or asynchronously via a message listener.
Rate-limited flow control: It is possible to control the rate at which a consumer can consume
messages. This is a form of throttling and can be used to ensure that a consumer never consumes
messages at a rate faster than the rate specified. The rate must be a positive integer to enable this
functionality and is the maximum desired message consumption rate specified in units of
4 52
messages per second. Setting this to -1 disables rate limited flow control. The default value is -1.
Examp le 18.8. R at e limit ed f lo w co n t ro l u sin g JMS
If JND I is used to look up the connection factory, the max rate can be configured in
stand al o ne. xml or d o mai n. xml :
<connectors>
<connector-ref connector-name="netty-connector"/>
</connectors>
<entries>
<entry name="ConnectionFactory"/>
</entries>

<consumer-max-rate>10</consumer-max-rate>
If the connection factory is directly instantiated, the max rate size can be set via the
Ho rnetQ C o nnecti o nFacto ry. setC o nsumerMaxR ate(i nt co nsumerMaxR ate) method.
Producer flow control - limits the amount of data sent from a client to a server to prevent the server
being overwhelmed.
Window based flow control: HornetQ producers, by default, can only send messages to an address
as long as they have sufficient credits to do so. The amount of credits required to send a message
is given by the size of the message. As producers run low on credits they request more from the
server, when the server sends them more credits they can send more messages. The amount of
credits a producer requests in one go is known as the window size.
Examp le 18.9 . Pro d u cer win d o w siz e f lo w co n t ro l u sin g JMS
If JND I is used to look up the connection factory, the producer window size can be configured
in stand al o ne. xml or d o mai n. xml :
<connectors>
</connectors>
<entries>
</entries>
<producer-window-size>10</producer-window-size>
If the connection factory is directly instantiated, the producer window size can be set via the
Ho rnetQ C o nnecti o nFacto ry. setP ro d ucerWi nd o wSi ze(i nt pro d ucerWi nd o wSi ze)
method.
Report a bug
18.8.15. Reference for Hornet Q Configurat ion At t ribut es
4 53
The JBoss EAP 6 implementation of HornetQ exposes the following attributes for configuration. You
can use the Management CLI to show the configurable or viewable attributes with the read reso urce operation.
Examp le 18.10. U se read - reso u rce t o sh o w at t rib u t es

[standalone@ localhost:9999 /] /subsystem=messaging/hornetqserver=default:read-resource
T ab le 18.10. H o rn et Q At t rib u t es
At t rib u t e
D ef au lt
Valu e
T yp e
D escrip t io n
al l o w-fai l back
true
BOOLEAN
async-co nnecti o n-executi o nenabl ed
true
BOOLEAN
Whether this server will

automatically shutdown if
the original live server
comes back up
Whether incoming packets
on the server must be
handed off to a thread from
the thread pool for
processing
An address setting defines
some attributes that are
defined against an
address wildcard rather
than a specific queue
An acceptor defines a way
in which connections can
be made to the HornetQ
server
The name of a set of
live/backups that must
replicate with each other
Whether this server is a
backup server
Whether a replicated live
server must check the
current cluster to see if
there is already a live
server with the same node
ID
[D eprecated] Whether the
server is clustered
The password used by
cluster connections to
communicate between the
clustered nodes
The user used by cluster
connections to
communicate between the
clustered nodes
ad d ress-setti ng
accepto r
STRING
backup-g ro up-name
backup
false
BOOLEAN
check-fo r-l i ve-server
false
BOOLEAN
cl ustered
false
BOOLEAN
cl uster-passwo rd
C HANG E
ME! !
STRING
cl uster-user
HORNETQ.
CLUSTER.A
D MIN.USER
STRING
4 54
At t rib u t e
D ef au lt
Valu e
T yp e
cl uster-co nnecti o n
create-bi nd i ng s-d i r
true
BOOLEAN
create-jo urnal -d i r
true
BOOLEAN
co nnecti o n-ttl -o verri d e
-1L
LONG
co nnecti o n-facto ry
co nnecto r
co nnecto r-servi ce
d i vert
d i sco very-g ro up
fai l back-d el ay
5000
LONG
fai l o ver-o n-shutd o wn
false
BOOLEAN
20000
INT
g ro upi ng -hand l er
i d -cache-si ze
i n-vm-accepto r
i n-vm-co nnecto r
D escrip t io n
Cluster connections group
servers into clusters so
that messages can be load
balanced between the
nodes of the cluster
Whether the server must
create the bindings
directory on start up
Whether the server must
create the journal directory
on start up
If set, this will override how
long (in ms) to keep a
connection alive without
receiving a ping
D efines a connection
factory
A connector can be used
by a client to define how it
connects to a server
A messaging resource that
allows you to transparently
divert messages routed to
one address to some other
address, without making
any changes to any client
application logic
Multicast group to listen to
receive broadcast from
other servers announcing
their connectors
How long to wait before
failback occurs on live
server restart
Whether this backup server
(if it is a backup server)
must come live on a
normal server shutdown
Makes decisions about
which node in a cluster
must handle a message
with a group id assigned
The size of the cache for
pre-creating message ID s
D efines a way in which inVM connections can be
made to the HornetQ server
Used by an in-VM client to
define how it connects to a
server
4 55
At t rib u t e
D ef au lt
Valu e
T yp e
D escrip t io n
jmx-d o mai n
org.hornetq
STRING
jmx-manag ement-enabl ed
false
BOOLEAN
jo urnal -buffer-si ze
LONG
jo urnal -co mpact-mi n-fi l es
501760
(490KiB)
500000
(0.5
millisecond
s) for
ASYNCIO
journal and
3333333
(3.33
millisecond
s) for NIO
journal
10
The JMX domain used to

register internal HornetQ
MBeans in the
MBeanServer
Whether HornetQ must
expose its internal
management API via JMX.
This is not recommended,
as accessing these
MBeans can lead to
inconsistent configuration
The size of the internal
buffer on the journal
The timeout (in
nanoseconds) used to
flush internal buffers on
the journal
jo urnal -co mpact-percentag e
30
INT
jo urnal -fi l e-si ze
10485760
LONG
jo urnal -max-i o
INT
jo urnal -mi n-fi l es
INT
jo urnal -sync-no n-transacti o nal
true
BOOLEAN
jo urnal -sync-transacti o nal
true
BOOLEAN
jo urnal -buffer-ti meo ut
4 56
LONG
INT
The minimal number of

journal data files before we
can start compacting
The percentage of live data
on which we consider
compacting the journal
The size (in bytes) of each
journal file
write requests that can be
in the AIO queue at any
one time. The default value
changes to 500 when
ASYNCIO journal is used
How many journal files to
pre-create
Whether to wait for non
transaction data to be
synced to the journal
before returning a
response to the client
Whether to wait for
transaction data to be
synchronized to the
journal before returning a
response to the client
At t rib u t e
D ef au lt
Valu e
T yp e
D escrip t io n
jo urnal -type
ASYNCIO
String
jms-to pi c
l i ve-co nnecto r-ref
reference
STRING
l o g -jo urnal -wri te-rate
false
BOOLEAN
The type of journal to use.

This attribute can take the
values " ASYNCIO" or
" NIO"
D efines a JMS topic
[D eprecated] The name of
the connector used to
connect to the live
connector. If this server is
not a backup that uses
shared nothing HA, it's
value is " undefined"
Whether to periodically log
the journal's write rate and
flush rate
mask-passwo rd
manag ement-ad d ress
true
jms.queue.h
ornetq.man
agement
hornetq.noti
fications
BOOLEAN
STRING
max-saved -repl i cated -jo urnal si ze
INT
memo ry-measure-i nterval
-1
LONG
memo ry-warni ng -thresho l d
25
INT
messag e-co unter-enabl ed
false
BOOLEAN
messag e-co unter-max-d ayhi sto ry

messag e-co unter-sampl e-peri o d
10
INT
10000
LONG
messag e-expi ry-scan-peri o d
30000
LONG
messag e-expi ry-thread -pri o ri ty
INT
pag e-max-co ncurrent-i o
INT
perf-bl ast-pag es
-1
INT
manag ement-no ti fi cati o nad d ress
STRING
Address to send
management messages to
The name of the address
that consumers bind to in
order to receive
management notifications
backup journals to keep
after failback occurs
Frequency to sample JVM
memory in ms (or -1 to
disable memory sampling)
Percentage of available
memory which if exceeded
results in a warning log
Whether message counters
are enabled
How many days to keep
message counter history
The sample period (in ms)
to use for message
counters
How often (in ms) to scan
for expired messages
The priority of the thread
expiring messages
concurrent reads allowed
on paging
4 57
At t rib u t e
D ef au lt
Valu e
T yp e
D escrip t io n
persi st-d el i very-co unt-befo red el i very
false
BOOLEAN
persi st-i d -cache
true
BOOLEAN
persi stence-enabl ed
true
BOOLEAN
remo ti ng -i ntercepto rs
undefined
LIST
remo ti ng -i nco mi ng -i ntercepto rs
undefined
LIST
remo ti ng -o utg o i ng -i ntercepto rs
undefined
LIST
run-sync-speed -test
false
BOOLEAN
Whether the delivery count

is persisted before delivery.
False means that this only
happens after a message
has been canceled
Whether ID s are persisted
to the journal
Whether the server will use
the file based journal for
persistence
D efines a managed
connection factory
[D eprecated] The list of
interceptor classes used
by this server
The list of incoming
by this server
The list of outgoing
by this server
Whether to perform a
diagnostic test on how fast
your disk can sync on
startup. Useful when
determining performance
issues
The name of the cluster
connection to replicate
from if more than one
cluster connection is
configured
A runtime queue
Used by a remote client to
define how it connects to a
server
D efines a way in which
remote connections can be
made to the HornetQ server
The number of threads that
the main scheduled thread
pool has
The security domain to use
in order to verify user and
role information
Whether security is
enabled
A security setting allows
sets of permissions to be
defined against queues
based on their address
po o l ed -co nnecti o n-facto ry
STRING
repl i cati o n-cl ustername
runti me-q ueue

remo te-co nnecto r
remo te-accepto r
sched ul ed -thread -po o l -max-si ze
INT
securi ty-d o mai n
other
STRING
securi ty-enabl ed
true
BOOLEAN
securi ty-setti ng
4 58
At t rib u t e
D ef au lt
Valu e
T yp e
D escrip t io n
securi ty-i nval i d ati o n-i nterval
10000
LONG
server-d ump-i nterval
-1
LONG
shared sto re
true
BOOLEAN
thread -po o l -max-si ze
30
INT
transacti o n-ti meo ut
300000
LONG
transacti o n-ti meo ut-scanperi o d

wi l d -card -ro uti ng -enabl ed
1000
LONG
true
BOOLEAN
How long (in ms) to wait

before invalidating the
security cache
How often to dump basic
runtime information to the
server log. A value less
than 1 disables this feature
Whether this server is
using a shared store for
failover
The number of threads that
the main thread pool has. 1 means no limit
How long (in ms) before a
transaction can be
removed from the resource
manager after create time
How often (in ms) to scan
for timeout transactions
Whether the server
supports wild card routing
Warning
The value of jo urnal -fi l e-si ze must be higher than the size of message sent to server, or
the server will not be able to store the message.
Report a bug
18.8.16. Set Message Expiry

In t ro d u ct io n
Sent messages can be set to expire on server if they're not delivered to consumer after specified
amount of time (milliseconds). Using Java Messaging Service (JMS) or HornetQ Core API, the
expiration time can be set directly on the message. For example:
// message will expire in 5000ms from now
message.setExpiration(System.currentTimeMillis() + 5000);
JMS Messag eP ro d ucer includes a T i meT o Li ve parameter which controls message expiry for the
messages it sends:
// messages sent by this producer will be retained for 5s (5000ms)
before expiration
producer.setTimeToLive(5000);
Expired messages which are consumed from an expiry address have the following properties:
_HQ_ORIG_AD D RESS
4 59
A string property containing the original address of the expired message.

_HQ_ACTUAL_EXPIRY
A long property containing the actual expiration time of the expired message.
Besides setting the time-to-live parameter on the JMS producer, you can also set it on a per-message
basis. You can achieve this by adding TTL parameter to producer's send method when sending the
message.
producer.send(message, DeliveryMode.PERSISTENT, 0, 5000)
Where, the last parameter is message specific TTL.
C o n f ig u rin g Exp iry Ad d resses
Expiry address are defined in the address-setting configuration:

<expiry-address>jms.queue.expiryQueue</expiry-address>
</address-setting>
If the messages are expired and no expiry address is specified, the messages are removed from the
queue and dropped.
C o n f ig u rin g Exp iry R eap er T h read
A reaper thread periodically inspects the queues to validate if messages have expired.
message-expiry-scan-period
How often the queues will be scanned to detect expired messages (in milliseconds, default is
30000ms, set to -1 to disable the reaper thread).
message-expiry-thread-priority
The reaper thread priority. It must be between 0 and 9, 9 being the highest priority, default is 3.
Report a bug
18.9. PRE_ACKNOWLEDGE mode

JMS specifies three acknowledgement modes:
AUTO_ACKNOWLED GE
CLIENT_ACKNOWLED GE
D UPS_OK_ACKNOWLED GE
HornetQ supports two additional modes: PRE_ACKNOWLED GE and IND IVID UAL_ACKNOWLED GE.
In some scenarios you could afford to lose messages in event of failure, so it would help to
acknowledge the message on the server before delivering it to the client.
4 60
This extra mode is supported by HornetQ and is called as pre-acknowledge mode.

The disadvantage of acknowledging the messages on the server before delivery is that the message
is lost if the system crashes after acknowledging the message on the server but before it is delivered
to the client. In that case, the message is lost and will not be recovered when the system restart.
D epending on the messaging case, pre-acknowledgement mode can avoid extra network traffic and
CPU at the cost of coping with message loss.
An example use case for pre-acknowledgement is related to stock price update messages. With these
messages it might be reasonable to lose a message in event of crash, since the next price update
message will arrive soon, overriding the previous price.
Note
If you use pre-acknowledge mode, then you will lose transactional semantics for messages
being consumed, since they are being acknowledged first on the server, not when you commit
the transaction.
Report a bug
18.9.1. Using PRE_ACKNOWLEDGE

The pre-acknowledgement mode can be configured in the stand al o ne. xml or d o mai n. xml file
on the connection factory.
<connectors>
</connectors>
<entries>
</entries>
<pre-acknowledge>true</pre-acknowledge>
Alternatively, to use pre-acknowledgement mode using the JMS API, create a JMS Session with the
HornetQSession.PRE_ACKNOWLEDGE constant.
// messages will be acknowledge on the server *before* being delivered to
the client
Session session = connection.createSession(false,
HornetQJMSConstants.PRE_ACKNOWLEDGE);
Alternatively, you can set pre-acknowledge directly on the Ho rnetQ C o nnecti o nFacto ry instance
using the setter method.
To use pre-acknowledgement mode using the core API you can set it directly on the
C l i entSessi o nFacto ry instance by using the setter method.
Report a bug
18.9.2. Individual Acknowledge
4 61
A valid use-case for individual acknowledgement is when you need to have your own scheduling
and you do not know when your message processing will be finished. You prefer having one
consumer per thread worker but this is not possible in some circumstances depending on how
complex is your processing. For that you can use the individual acknowledgement.
You must setup Individual Acknowledge by creating a session with the acknowledge mode with
HornetQJMSConstants.INDIVIDUAL_ACKNOWLEDGE. Individual Acknowledge inherits all the
semantics from Client Acknowledge, with the exception the message is individually acknowledged.
Note
To avoid confusion on MD B processing, Individual ACKNOWLED GE is not supported through
MD Bs (or the inbound resource adapter). This is because you have to finish the process of
your message inside the MD B
Report a bug
18.10. T hread Management

18.10.1. Server-Side T hread Management
Each HornetQ Server maintains a single thread pool for general use, and scheduled thread pool for
scheduled use. A Java scheduled thread pool cannot be configured to use a standard thread pool,
otherwise we could use a single thread pool for both scheduled and non scheduled activity.
When using old (blocking) IO, a separate thread pool is used to service connections. Since old IO
requires a thread per connection, it is not recommended to get the threads from the standard pool as
the pool will get exhausted if too many connections are made. This results in the server hanging,
since it has no remaining threads to do anything else. If you require the server to handle many
concurrent connections you must use NIO, not old IO.
When using new IO (NIO), by default, HornetQ uses a number of threads equal to three times the
number of cores (or hyper-threads) as reported by
. g etR unti me(). avai l abl eP ro cesso rs()Runtime for processing incoming packets. To
override this value, you can set the number of threads by specifying the nio-remoting-threads
parameter in the transport configuration.
Report a bug
1 8 .1 0 .1 .1 . Se rve r Sche dule d T hre ad Po o l

The server scheduled thread pool is used for most activities on the server side that require running
periodically or with delays. It maps internally to a
java. uti l . co ncurrent. Sched ul ed T hread P o o l Executo r instance.
The maximum number of thread used by this pool is configured in stand al o ne. xml or
d o mai n. xml using the scheduled-thread-pool-max-size parameter. The default value is 5
threads. A small number of threads is usually sufficient for this pool.
Report a bug
1 8 .1 0 .1 .2 . Ge ne ral Purpo se Se rve r T hre ad Po o l
4 62
The general purpose thread pool is used for most asynchronous actions on the server side. It maps
internally to a java. uti l . co ncurrent. T hread P o o l Executo r instance.
The maximum number of thread used by this pool is configured in stand al o ne. xml or
d o mai n. xml using the thread-pool-max-size parameter.
If a value of -1 is used, the thread pool has no upper bound and new threads are created on demand
if there are not enough threads available to fulfill a request. If activity later subsides then threads are
timed-out and closed.
If a value of n, where n is a positive integer greater than zero, is used then the thread pool is
bounded. If more requests come in and there are no free threads are available in the pool and the
pool is full then requests will block until a thread becomes available. It is recommended that a
bounded thread pool is used with caution since it can lead to dead-lock situations if the upper
bound is chosen to be too low.
The default value for thread-pool-max-size is 30.
Report a bug
1 8 .1 0 .1 .3. Expiry Re ape r T hre ad

A single thread is also used on the server side to scan for expired messages in queues. We cannot
use either of the thread pools for this since this thread needs to run at its own configurable priority.
Report a bug
1 8 .1 0 .1 .4 . Asynchro no us IO
Asynchronous IO has a thread pool for receiving and dispatching events out of the native layer. It is
on a thread dump with the prefix Ho rnetQ -AIO -po l l er-po o l . HornetQ uses one thread per
opened file on the journal (there is usually one).
There is also a single thread used to invoke writes on l i bai o . It is done to avoid context switching
on l i bai o that would cause performance issues. This thread is found on a thread dump with the
prefix Ho rnetQ -AIO -wri ter-po o l .
Report a bug
18.10.2. Client -Side T hread Management

On the client side, HornetQ maintains a single static scheduled thread pool and a single static
general thread pool for use by all clients using the same classloader in that JVM instance.
The static scheduled thread pool has a maximum size of 5 threads, and the general purpose thread
pool has an unbounded maximum size.
If required HornetQ can also be configured so that each C l i entSessi o nFacto ry instance does
not use these static pools but instead maintains its own scheduled and general purpose pool. Any
sessions created from that C l i entSessi o nFacto ry will use those pools instead.
To configure a C l i entSessi o nFacto ry instance to use its own pools, use the appropriate setter
methods immediately after creation. For example:
ServerLocator locator = HornetQClient.createServerLocatorWithoutHA(...)
ClientSessionFactory myFactory = locator.createClientSessionFactory();
myFactory.setUseGlobalPools(false);
myFactory.setScheduledThreadPoolMaxSize(10);
4 63
myFactory.setThreadPoolMaxSize(-1);
If you are using the JMS API, you can set the same parameters on the C l i entSessi o nFacto ry
and use it to create the ConnectionFactory instance. For example:
ConnectionFactory myConnectionFactory =
HornetQJMSClient.createConnectionFactory(myFactory);
If you are using JND I to instantiate Ho rnetQ C o nnecti o nFacto ry instances, you can also set
these parameters in the stand al o ne. xml or d o mai n. xml file where you describe your connection
factory. For example:
<connectors>
</connectors>
<entries>
<entry name="XAConnectionFactory"/>
</entries>
<use-global-pools>false</use-global-pools>
<scheduled-thread-pool-max-size>10</scheduled-thread-pool-max-size>
<thread-pool-max-size>-1</thread-pool-max-size>
Report a bug
18.11. Message Grouping

18.11.1. About Message Grouping
A message group is a set/group of messages which share certain characteristics:
All messages in a message group are grouped under a common group id. This means that they
can be identified with a common group property
All messages in a message group are serially processed and consumed by the same consumer
irrespective of the number of customers on the queue. This means that a specific message group
with a unique group id is always processed by one consumer when the consumer opens it. If the
consumer closes the message group the entire message group is directed to another consumer in
the queue
Important
Message groups are especially useful when there is a need for messages with a certain value
of the property (group id) to be processed serially by a single consumer.
Report a bug
18.11.2. Using Hornet Q Core API on Client Side
4 64
The property _HQ _G R O UP _ID is used to identify a message group in HornetQ Core API on client
side. To pick a random unique message group identifier you can also set the auto -g ro up property
as true on the SessionFactory.
Report a bug
18.11.3. Configuring Server for Java Messaging Service (JMS) Client s

The property JMSXG ro upID is used to identify a message group for Java Messaging Service (JMS)
clients. If you wish to send a message group with different messages to one consumer you can set
the same JMSXG ro upID for different messages:
Message message = ...
message.setStringProperty("JMSXGroupID", "Group-0");
message = ...
message.setStringProperty("JMSXGroupID", "Group-0");
The second approach is to set the auto -g ro up property to true on the
Ho rnetQ C o nnecto nFacto ry. The Ho rnetQ C o nnecti o nFacto ry will then pick up a random
unique message group identifier. You can set the auto -g ro up property in server configuration files
(stand al o ne. xml and d o mai n. xml ) as follows:
<connectors>
</connectors>
<entries>
</entries>
<auto-group>true</auto-group>
An alternative to the above methods is to set a specific message group identifier through the
connection factory. This will in turn set the property JMSXG ro upID to the specified value for all
messages sent through this connection factory. To set a specific message group identifier on the
connection factory, edit the g ro up-i d property in server configuration files (stand al o ne. xml and
d o mai n. xml ) as follows:
<connectors>
</connectors>
<entries>
</entries>
<group-id>Group-0</group-id>
Report a bug
18.11.4 . Clust ered Grouping
4 65
Clustered grouping follows a different approach relative to normal message grouping. In a cluster,
message groups with specific group ids can arrive on any of the nodes. It is important for a node to
determine which group ids are bound to which consumer on which node. Each node is responsible
for routing message groups correctly to the node which has the consumer processing those group
ids irrespective of where the message groups arrive by default. Once messages with a given group id
are sent to a specific consumer connected to the given node in the cluster, then those messages are
never sent to another node even if the consumer is disconnected.
This situation is addressed by a grouping handler. Each node has a grouping handler and this
grouping handler (along with other handlers) is responsible for routing the message groups to the
correct node. There are two types of grouping handlers namely l o cal and remo te.
The local handler is responsible for deciding the route which a message group should take. The
remote handlers communicate with the local handler and work accordingly. Each cluster should
choose a specific node to have a local grouping handler and all the other nodes should have remote
handlers.
Warning
If message grouping is used in cluster, it breaks if the server with configured remote grouping
handler fails. Setting up backup for remote grouping handler also does not have affect.
You can configure " local" and " remote" grouping handlers in server configuration files
(stand al o ne. xml and d o mai n. xml ) as follows:
<grouping-handler name="my-grouping-handler">
<type>LOCAL</type>
<timeout>5000</timeout>
</grouping-handler>
<grouping-handler name="my-grouping-handler">
<type>REMOTE</type>
</grouping-handler>
The " timeout" attribute ensures that a routing decision is made quickly within the specified time. If a
decision is not made within this time an exception is thrown.
The node which initially receives a message group takes the routing decision based on regular
cluster routing conditions (round-robin queue availability). The node proposes this decision to the
respective grouping handler which then routes the messages to the proposed queue if it accepts the
proposal.
If the grouping handler rejects the proposal, it proposes some other route and the routing takes place
accordingly. The other nodes follow suite and forward the message groups to the chosen queue.
After a message arrives on a queue it is pinned to a customer on that queue.
Report a bug
18.11.5. Best Pract ices for Clust ered Grouping

Some best practices for clustered grouping are as follows:
4 66
If you create and close consumers regularly make sure that your consumers are distributed evenly
across the different nodes. Once a queue is pinned, messages are automatically transferred to
that queue regardless of removing customers from it
If you wish to remove a queue which has a message group bound to it, make sure the queue is
deleted by the session that is sending the messages. D oing this will ensure that other nodes will
not try to route messages to this queue after it is removed
As a failover mechanism always replicate the node which has the local grouping handler
Report a bug
18.12. Duplicat e Message Det ect ion

18.12.1. About Duplicat e Message Det ect ion
D uplicate message detection allows filtering of duplicate messages without the need of coding the
duplicate detection logic within the application. You can configure duplicate message detection in
HornetQ.
When a sender(client/server) sends a message to another server there can be a situation where the
target server(receiver) or the connection fails after sending the message but before sending a
response to the sender indicating that the process was successful. In such situations, it is very
difficult for the sender(client) to determine if the message was sent successfully to the intended
receiver.
The message send may or may not be successful depending on when the target receiver or
connection failed (before or after sending the message). If the sender (client/server) decides to resend
the last message it can result in a duplicate message being sent to the address.
HornetQ provides duplicate message detection for messages sent to addresses.
Report a bug
18.12.2. Using Duplicat e Message Det ect ion for Sending Messages
To enable duplicate message detection for sent messages you need to set a special property on the
message to a unique value. You can create this value the way you wish but this value must be
unique.
When the target server receives this message, it checks if the special property is set. If the property is
set then the target server checks its memory cache for a received message with that value of the
header. If the server finds any message with the same value of the header it ignores the message sent
by a client.
If you are sending messages in a transaction then you do not have to set the property for every
message you send in that transaction; you only need to set it once in the transaction. If the server
detects a duplicate message for any message in the transaction, then it will ignore the entire
transaction.
The name of the property that you set is given by the value of
org.hornetq.api.core.HDR_DUPLICATE_DETECTION_ID, which is _HQ_DUPL_ID. The value of
this property can be of type byte[] or Si mpl eStri ng for core API. For Java Messaging Service
(JMS) clients, it must be of the type Stri ng with a unique value. An easy way of generating a unique
id is by generating a UUID .
The following example shows how to set the property for core API:
4 67
...
ClientMessage message = session.createMessage(true);
SimpleString myUniqueID = "This is my unique id";
this
// Can use a UUID for
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID, myUniqueID);
...
The following example shows how to set the property for JMS clients:
...
Message jmsMessage = session.createMessage();
String myUniqueID = "This is my unique id";
this
// Could use a UUID for
message.setStringProperty(HDR_DUPLICATE_DETECTION_ID.toString(),
myUniqueID);
...
Report a bug
18.12.3. Configuring Duplicat e ID Cache

The server maintains caches of received values of the
org.hornetq.core.message.impl.HDR_DUPLICATE_DETECTION_ID property sent to each
address. Each address maintains its own address cache.
The cache is fixed in terms of size. The maximum size of cache is configured using the parameter idcache-size in server configuration files (stand al o ne. xml and d o mai n. xml ). The default value
of this parameter is 2000 elements. If the cache has a maximum size of n elements, then the (n + 1)th
ID stored will overwrite the 0th element in the cache.
The caches can also be configured to persist to disk or not. This can be configured using the
parameter persist-id-cache in server configuration files (stand al o ne. xml and
d o mai n. xml ). If this value is set " true" then each ID will be persisted to permanent storage as they
are received. The default value for this parameter is true.
Note
Set the size of the duplicate ID cache to a large size in order to ensure that resending of
messages does not overwrite the previously sent messages stored in the cache.
Report a bug
18.12.4 . Using Duplicat e Det ect ion wit h Bridges and Clust er Connect ions
Core bridges can be configured to automatically add a unique duplicate ID value (if there isn't
4 68
already one in the message) before forwarding the message to the target. To configure a core bridge
for duplication message detection set the property use-duplicate-detection to " true" in server
configuration files (stand al o ne. xml and d o mai n. xml ). The default value of this parameter is
" true" .
Cluster connections internally use core bridges to move messages between nodes of the cluster. To
configure a cluster connection for duplicate message detection set the property use-duplicatedetection to " true" in server configuration files (stand al o ne. xml and d o mai n. xml ). The
default value of this parameter is " true" .
Report a bug
18.13. JMS Bridges

18.13.1. About Bridges
The function of a bridge is to consume messages from a source queue, and forward them to a target
address, typically on a different HornetQ server. Bridges cope with unreliable connections,
automatically reconnecting when the connections become available again. HornetQ bridges can be
configured with filter expressions to only forward certain messages.
Important
JMS bridge cannot be deployed to EAP 6 server, which includes HornetQ configured as a
dedicated backup. The reason is that Transaction Manager on a dedicated backup server is
unable to recover transactions previously started on the HornetQ live server.
Report a bug
18.13.2. Creat e a JMS Bridge

Su mmary
A JMS bridge consumes messages from a source JMS queue or topic and sends them to a target
JMS queue or topic, which is typically on a different server. It can be used to bridge messages
between any JMS servers, as long as they are JMS 1.1 compliant. The source and destination JMS
resources are looked up using JND I and the client classes for the JND I lookup must be bundled in a
module. The module name is then declared in the JMS bridge configuration.
Pro ced u re 18.2. C reat e a JMS B rid g e
This procedure demonstrates how to configure a JMS bridge to migrate messages from a JBoss EAP
5.x server to a JBoss EAP 6 server.
1. Configure the Bridge On the Source JMS Messaging Server
Configure the JMS bridge on the source server using the instructions provided for that server
type. For an example of how to configure a JMS Bridge for a JBoss EAP 5.x server, see the
topic entitled Create a JMS Bridge in the Migration Guide for JBoss EAP 6.
2. Configure the Bridge on the D estination JBoss EAP 6 Server
In JBoss EAP 6.1 and later, the JMS bridge can be used to bridge messages from any JMS
1.1 compliant server. Because the source and target JMS resources are looked up using
4 69
JND I, the JND I lookup classes of the source messaging provider, or message broker, must be
bundled in a JBoss Module. The following steps use the fictitious 'MyCustomMQ' message
broker as an example.
a. Create the JBoss module for the messaging provider.
i. Create a directory structure under
EAP_HOME/mo d ul es/system/l ayers/base/ for the new module. The
mai n/ subdirectory will contain the client JARs and mo d ul e. xml file. The
following is an example of the directory structure created for the MyCustomMQ
messaging provider:
EAP_HOME/mo d ul es/system/l ayers/base/o rg /mycusto mmq /mai n/
ii. In the mai n/ subdirectory, create a mo d ul e. xml file containing the module
definition for the messaging provider. The following is an example of the
mo d ul e. xml created for the MyCustomMQ messaging provider.
<module xmlns="urn:jboss:module:1.1"
name="org.mycustommq">
<properties>
<property name="jboss.api" value="private"/>
</properties>
<resources>

<resource-root path="mycustommq-1.2.3.jar" />
<resource-root path="mylogapi-0.0.1.jar" />
</resources>
<dependencies>

<module name="javax.api" />
<module name="javax.jms.api" />


<module name="org.hornetq" />
</dependencies>
</module>
iii. Copy the messaging provider JARs required for the JND I lookup of the source
resources to the module's mai n/ subdirectory. The directory structure for the
MyCustomMQ module should now look like the following.
modules/
`-- system
`-- layers
`-- base
`-- org
`-- mycustommq
4 70
`-- main
|-- mycustommq-1.2.3.jar
|-- mylogapi-0.0.1.jar
|-- module.xml
b. Configure the JMS bridge in the messag i ng subsystem of the JBoss EAP 6 server.
i. Before you begin, stop the server and back up the current server configuration
files. If you are running a standalone server, this is the
EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne-ful l -ha. xml
file. If you are running a managed domain, back up both the
EAP_HOME/d o mai n/co nfi g urati o n/d o mai n. xml and the
EAP_HOME/d o mai n/co nfi g urati o n/ho st. xml files.
ii. Add the jms-bri d g e element to the messag i ng subsystem in the server
configuration file. The so urce and targ et elements provide the names of the
JMS resources used for JND I lookups. If user and passwo rd credentials are
specified, they are passed as arguments when JMS connection is created.
The following is an example of the jms-bri d g e element configured for the
MyCustomMQ messaging provider:
...
<jms-bridge name="myBridge" module="org.mycustommq">
<source>
<connection-factory name="ConnectionFactory"/>
<destination name="sourceQ"/>
<user>user1</user>
<password>pwd1</password>
<context>
<property key="java.naming.factory.initial"
value="org.mycustommq.jndi.MyCustomMQInitialContextFact
ory"/>
<property key="java.naming.provider.url"
value="tcp://127.0.0.1:9292"/>
</context>
</source>
<target>
<connection-factory
name="java:/ConnectionFactory"/>
<destination name="/jms/targetQ"/>
</target>
<quality-of-service>DUPLICATES_OK</quality-ofservice>
<failure-retry-interval>500</failure-retryinterval>
<max-retries>1</max-retries>
<max-batch-size>500</max-batch-size>
<max-batch-time>500</max-batch-time>
<add-messageID-in-header>true</add-messageID-inheader>
</jms-bridge>
</subsystem>
4 71
In the above example, the JND I properties are defined in the co ntext element
for the so urce. If the co ntext element is omitted, as in the targ et example
above, the JMS resources are looked up in the local instance.
Report a bug
18.14 . Persist ence

18.14 .1. About Persist ence in Hornet Q
HornetQ handles its own persistence. It ships with a high-performance journal, which is optimized for
messaging-specific use cases.
The HornetQ journal is append only with a configurable file size, which improves performance by
enabling single write operations. It consists of a set of files on disk, which are initially pre-created to
a fixed size and filled with padding. As server operations (add message, delete message, update
message, etc.) are performed, records of the operations are appended to the journal until the journal
file is full, at which point the next journal file is used.
A sophisticated garbage collection algorithm determines whether journal files can be reclaimed and
re-used when all of their data has been deleted. A compaction algorithm removes dead space from
journal files and compresses the data.
The journal also fully supports both local and XA transactions.
The majority of the journal is written in Java, but interaction with the file system has been abstracted
to allow different pluggable implementations. The two implementations shipped with HornetQ are:
Java New I/O (NIO)
Uses standard Java NIO to interface with the file system. This provides extremely good
performance and runs on any platform with a Java 6 or later runtime.
Linux Asynchronous IO (AIO)
Uses a native code wrapper to talk to the Linux asynchronous IO library (AIO). With AIO, HornetQ
receives a message when data has been persisted. This removes the need for explicit syncs. AIO
will typically provide better performance than Java NIO, but requires Linux kernel 2.6 or later and
the libaio package.
AIO also requires ext2, ext3, ext4, jfs or xfs type file systems.
The standard HornetQ core server uses the following journal instances:
bindings journal
Stores bindings-related data, including the set of queues deployed on the server and their
attributes. It also stores data such as ID sequence counters. The bindings journal is always a NIO
journal, as it typically has low throughput in comparison to the message journal.
The files on this journal are prefixed as hornetq-bindings. Each file has a bindings extension. File
size is 1048576 bytes, and it is located in the bindings folder.
JMS journal
4 72
Stores all JMS-related data, for example, any JMS queues, topics or connection factories and any
JND I bindings for these resources. Any JMS resources created with the management API are
persisted to this journal. Any resources configured with configuration files are not. This journal is
created only if JMS is in use.
message journal
Stores all message-related data, including messages themselves and duplicate-id caches. By
default, HornetQ uses AIO for this journal. If AIO is not available, it will automatically fall back to
NIO.
Large messages are persisted outside the message journal. In low memory situations, configure
HornetQ to page messages to disk. If persistence is not required, HornetQ can be configured not to
persist any data.
Report a bug
18.14 .2. Import or Export t he Journal Dat a

You may want to inspect the existent records on each one of the journals used by HornetQ, and you
can use the export/import tool for that purpose. The export/import are classes located in the
EAP_HOME/bi n/cl i ent/jbo ss-cl i ent. jar, you can export the journal as a text file by using
this command:
java -cp jbo ss-cl i ent. jar o rg . ho rnetq . co re. jo urnal . i mpl . Expo rtJo urnal
<Jo urnal D i recto ry> <Jo urnal P refi x> <Fi l eExtensi o n> <Fi l eSi ze> <Fi l eO utput>
To import the file as binary data on the journal:
java -cp jbo ss-cl i ent. jar o rg . ho rnetq . co re. jo urnal . i mpl . Impo rtJo urnal
<Jo urnal D i recto ry> <Jo urnal P refi x> <Fi l eExtensi o n> <Fi l eSi ze> <Fi l eInput>
JournalD irectory: Use the configured folder for your selected folder. Example:./hornetq/data/journal
JournalPrefix: Use the prefix for your selected journal, as discussed
FileExtension: Use the extension for your selected journal, as discussed
FileSize: Use the size for your selected journal, as discussed
FileOutput: text file that will contain the exported data
Report a bug
18.15. Hornet Q Clust ering

HornetQ clusters are used to create groups of HornetQ servers in order to share message processing
load. Each active node in the cluster acts as an independent HornetQ server and manages its own
messages and connections.
To form a cluster, each node (independent HornetQ server) declares cluster connections with another
node with configuration parameters in server configuration files (stand al o ne. xml and
d o mai n. xml ).
In clustering, core bridges are used for bridging/routing messages from one cluster to another. Core
bridges consume messages from a source queue and then forward these messages to a target
HornetQ server (node) which may or may not be in the same cluster.
4 73
When a node forms a cluster connection with another node, it creates a core bridge internally. Each
node creates an explicit core bridge and you do not need to declare it. These cluster connections
allow transmission of messages between nodes in various clusters for balancing message
processing load.
You can configure cluster nodes in server configuration files (stand al o ne. xml and
d o mai n. xml ).
Important
You can configure a node through server configuration files (stand al o ne. xml and
d o mai n. xml ) and copy this configuration to other nodes to generate a symmetric cluster.
However you must be careful when you are copying the server configuration files. You must
not copy the HornetQ data (i.e. the bindings, journal, and large messages directories) from
one node to another. When a node is started for the first time it persists a unique identifier to
the journal directory which is needed for proper formation of clusters.
Report a bug
18.15.1. About Server Discovery

Servers use a mechanism called " server discovery" to:
Forward their connection details to messaging clients: Messaging clients intend to connect to
servers of a cluster without specific details on the servers which are up and running at a given
point of time
Connect to other servers: Servers in a cluster want to establish cluster connections with other
servers without specific details on of all other servers in a cluster
Information about servers is sent to messaging clients via normal HornetQ connections and to other
servers via cluster connections.
The initial first connection needs to be established and it can be established using dynamic server
discovery techniques like UD P (User D atagram Protocol), JGroups or by providing a list of
connectors.
Report a bug
18.15.2. Broadcast Groups

Connectors are used on the client to define how and in what ways it connects to the server. Servers
use broadcast groups to broadcast connectors over the network. The broadcast group takes a set of
connector pairs and broadcasts them on the network. Each connector pair contains connection
settings for a live and backup server.
You can define broadcast groups in broadcast-groups element of server configuration files
(stand al o ne. xml and d o mai n. xml ). A single HornetQ server can have many broadcast groups.
You can define either a User D atagram Protocol (UD P) or a JGroup broadcast group.
Report a bug
1 8 .1 5 .2 .1 . Use r Dat agram Pro t o co l (UDP) Bro adcast Gro up

The example shown below defines a UD P broadcast group:
4 74
<broadcast-groups>
<broadcast-group name="my-broadcast-group">
<local-bind-address>172.16.9.3</local-bind-address>
<local-bind-port>5432</local-bind-port>
<group-address>231.7.7.7</group-address>
<group-port>9876</group-port>
</broadcast-group>
</broadcast-groups>
Note
In the configuration example shown above, the attributes " local-bind-address" , " local-bindport" , " group-address" and " group-port" are deprecated. Instead of these attributes you can
choose to use the attribute " socket-binding" .
The example shown below defines a UD P broadcast group replacing all the deprecated attributes
with the attribute " socket-binding" :
<broadcast-groups>
<broadcast-group name="my-broadcast-group">
</broadcast-group>
</broadcast-groups>
The table shown below describes all the important parameters used in the above examples and in
general to define a UD P broadcast group:
T ab le 18.11. U D P B ro ad cast G ro u p Paramet ers
At t rib u t e
D escrip t io n
name attribute
D enotes the name of each broadcast group in a

server. Each broadcast group must have a
unique name.
[D eprecated] This is a UD P specific attribute
and specifies the local bind address which the
datagram packet binds to. You must set this
property to define the interface which you wish
to use for your broadcasts. If this property is not
specified then the socket binds to a wildcard
address (a random kernel generated address).
[D eprecated] This is a UD P specific attribute
and is used to specify a local port which the
datagram socket binds to. A default value of " -1"
specifies an anonymous port to be used.
local-bind-address
local-bind-port
4 75
At t rib u t e
D escrip t io n
group-address
[D eprecated] This is a multicast address specific

to UD P where messages are broadcast. This IP
address has a range of 224.0.0.0 to
239.255.255.255, inclusive. The IP address
224.0.0 is reserved and can not be used.
[D eprecated] This denotes the UD P port number
for broadcasting.
This denotes the broadcast group socket
binding
This parameter specifies the time between two
broadcasts (milliseconds). It is optional.
This refers to the connector which will be
broadcasted.
group-port
socket-binding
broadcast-period
connector-ref
Report a bug
1 8 .1 5 .2 .2 . JGro ups Bro adcast Gro up

You can use JGroups to broadcast by specifying two attributes namely jgroups-stack and
jgroups-channel. The example shown below defines a JGroups broadcast group:
<broadcast-groups>
<broadcast-group name="bg-group1">
<jgroups-stack>udp</jgroups-stack>
<jgroups-channel>udp</jgroups-channel>
</broadcast-group>
</broadcast-groups>
The JGroups broadcast group definition uses two main attributes:
jgroups-stack attribute: This denotes the name of a stack defined in the
o rg . jbo ss. as. cl usteri ng . jg ro ups subsystem
jgroups-channel attribute: This denotes the channel which JGroups channels connect to for
broadcasting
Report a bug
18.15.3. Discovery Groups

Broadcast groups are used for broadcasting connectors over a network. On the other hand
discovery groups define how connector information is received from broadcast endpoints (UD P or
JGroups broadcast group). A discovery group maintains a list of connector pair- one for each
broadcast by a different server.
When a discovery group receives broadcasts on a broadcast endpoint for a specific server, it
accordingly updates the connector pairs entry in the list for the specific server. If it does not receive a
broadcast from a specific server for a long time, it removes the server's entry from the list altogether.
D iscovery groups are mainly used by cluster connections and Java Messaging Service (JMS) clients
to obtain initial connection information in order to download the required topology.
4 76
Note
You must configure each discovery group with an appropriate broadcast endpoint which
matches its broadcast group counterpart (UD P or JGroups).
Report a bug
1 8 .1 5 .3.1 . Co nfiguring Use r Dat agram Pro t o co l (UDP) Disco ve ry Gro up o n t he

Se rve r
The example shown below defines a UD P discovery group:
<discovery-groups>
<discovery-group name="my-discovery-group">
<local-bind-address>172.16.9.7</local-bind-address>
<group-address>231.7.7.7</group-address>
<group-port>9876</group-port>
</discovery-group>
</discovery-groups>
Note
In the configuration example shown above, the attributes " local-bind-address" , " groupaddress" and " group-port" are deprecated. Instead of these attributes you can choose to use
the attribute " socket-binding" .
The example shown below defines a UD P discovery group replacing all the deprecated attributes
with the attribute " socket-binding" :
<discovery-groups>
<discovery-group name="my-discovery-group">
</discovery-group>
</discovery-groups>
The table shown below describes all the important parameters used in the above example and in
general to define a discovery group:
T ab le 18.12. U D P D isco very G ro u p Paramet ers
At t rib u t e
D escrip t io n
name attribute
This attribute denotes the name of your

discovery group. Each discovery name must
have a unique name per server.
[D eprecated] This is an optional UD P specific
attribute. It is used to configure a discovery
group to listen on a specific interface when
using multiple interfaces on the same machine.
local-bind-address
4 77
At t rib u t e
D escrip t io n
group-address
[D eprecated] This is a compulsory UD P specific

attribute. It is used to configure a discovery
group to listen on the multicast IP address of a
group. The value of this attribute must match the
group-address attribute of the broadcast
group that you wish to listen from.
[D eprecated] This is a compulsory UD P specific
attribute. It is used to configure the UD P port of
the multicast group. The value of this attribute
must match the group-port attribute of the
multicast group that you wish to listen from.
This denotes the discovery group socket
binding
This is an optional UD P specific attribute. It is
used to configure the time period (in
milliseconds) for which the discovery group
waits before removing a server's connector pair
entry from the list after receiving the last
broadcast from that server. The value of
refresh-timeout must be set significantly
higher than the value of broadcast-period
attribute on the broadcast group to prevent
quick removal servers from the list when the
broadcast process is still on. The default value
of this attribute is 10,000 milliseconds.
group-port
socket-binding
refresh-timeout
Report a bug
1 8 .1 5 .3.2 . Co nfiguring JGro ups Disco ve ry Gro up o n t he Se rve r

The example shown below defines a JGroups discovery group:
<discovery-groups>
<discovery-group name="dg-group1">
<jgroups-stack>udp</jgroups-stack>
<jgroups-channel>udp</jgroups-channel>
</discovery-group>
</discovery-groups>
The JGroups discovery group definition uses two main attributes:
jgroups-stack attribute: This denotes the name of a stack defined in the
o rg . jbo ss. as. cl usteri ng . jg ro ups subsystem
jgroups-channel attribute: This attribute denotes the channel which JGroups channels
connect to for receiving broadcasts
Note
JGroup attributes and UD P specific attributes are exclusive. You can use either JGroup or
UD P set of attributes in the configuration of a discovery group or a broadcast group
4 78
Report a bug
1 8 .1 5 .3.3. Co nfiguring Disco ve ry Gro ups fo r Java Me ssaging Se rvice (JMS) Clie nt s
D iscovery groups can be configured for JMS and core clients. You can specify the discovery group
to be used for a JMS connection factory in server configuration files (stand al o ne. xml and
d o mai n. xml ):
<discovery-group-ref discovery-group-name="my-discovery-group"/>
<entries>
</entries>
The element discovery-group-ref is used to specify the name of a discovery group. When a
client application downloads this connection factory from Java Naming and D irectory Interface
(JND I) and creates JMS connections, these connections are load balanced across all the servers
which the discovery group maintains by listening on the multicast address specified in the discovery
group configuration.
If you are using JMS but not JND I to lookup for a connection factory then you can specify the
discovery group parameters directly when creating the JMS connection factory:
final String groupAddress = "231.7.7.7";
final int groupPort = 9876;
ConnectionFactory jmsConnectionFactory =
HornetQJMSClient.createConnectionFactory(new
DiscoveryGroupConfiguration(groupAddress, groupPort, new
UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1)),
JMSFactoryType.CF);
Connection jmsConnection1 = jmsConnectionFactory.createConnection();
Connection jmsConnection2 = jmsConnectionFactory.createConnection();
The default value of refresh-timeout attribute can be set on D iscoveryGroupConfiguration by
using the setter method setD i sco veryR efreshT i meo ut(). For the connection factory to wait for
a specific amount of time before creating the first connection, you can use the setter method
setD i sco veryIni ti al Wai tT i meo ut() on D iscoveryGroupConfiguration.
D oing this ensures that the connection factory has enough time to receive broadcasts from all the
nodes in the cluster. The default value for this parameter is 10000 milliseconds.
Report a bug
1 8 .1 5 .3.4 . Co nfiguring disco ve ry fo r Co re API

If you are using the core API to directly instantiate ClientSessionFactory instances, then you
can specify the discovery group parameters directly when creating the session factory:
final String groupAddress = "231.7.7.7";
final int groupPort = 9876;
ServerLocator factory = HornetQClient.createServerLocatorWithHA(new
DiscoveryGroupConfiguration(groupAddress, groupPort, new
4 79
UDPBroadcastGroupConfiguration(groupAddress, groupPort, null, -1))));

ClientSessionFactory factory = locator.createSessionFactory();
ClientSession session1 = factory.createSession();
ClientSession session2 = factory.createSession();
The default value of refresh-timeout attribute can be set on D iscoveryGroupConfiguration by
using the setter method setD i sco veryR efreshT i meo ut(). You can use
setD i sco veryIni ti al Wai tT i meo ut() on D iscoveryGroupConfiguration for the session factory
to wait for a specific amount of time before creating a session.
Report a bug
18.15.4 . Server Side Load Balancing

There is one important cluster topology:
Symmetric Cluster: In a symmetric cluster every cluster node is connected directly to every other
node in the cluster. To create a symmetric cluster every node in the cluster defines a cluster
connection with the attribute max-hops set to 1.
Note
In a symmetric cluster each node knows about all the queues that exist on all the other
nodes and what consumers they have. With this knowledge it can determine how to load
balance and redistribute messages around the nodes.
Report a bug
1 8 .1 5 .4 .1 . Co nfiguring Clust e r Co nne ct io ns

Cluster connections are configured in server configuration files (stand al o ne. xml and
d o mai n. xml ) in the element cluster-connection. There can be zero or more cluster
connections defined per HornetQ server.
<cluster-connections>
<connector-ref>netty-connector</connector-ref>
<check-period>1000</check-period>
<connection-ttl>5000</connection-ttl>
<min-large-message-size>50000</min-large-message-size>
<call-timeout>5000</call-timeout>
<retry-interval>500</retry-interval>
<retry-interval-multiplier>1.0</retry-interval-multiplier>
<max-retry-interval>5000</max-retry-interval>
<reconnect-attempts>-1</reconnect-attempts>
<use-duplicate-detection>true</use-duplicate-detection>
<forward-when-no-consumers>false</forward-when-no-consumers>
<max-hops>1</max-hops>
<confirmation-window-size>32000</confirmation-window-size>
<call-failover-timeout>30000</call-failover-timeout>
<notification-interval>1000</notification-interval>
4 80
<notification-attempts>2</notification-attempts>
<discovery-group-ref discovery-group-name="my-discovery-group"/>
</cluster-connections>
The following table defines the configurable attributes:
T ab le 18.13. C lu st er C o n n ect io n s C o n f ig u rab le At t rib u t es
At t rib u t e
D escrip t io n
address
Each cluster connection only

applies to messages sent to an
address that starts with this
value. The address can be any
value and you can have many
cluster connections with
different values of addresses,
simultaneously balancing
messages for those addresses,
potentially to different clusters
of servers. This does not use
wild card matching.
This is a compulsory attribute
which refers to the connector
sent to other nodes in the
cluster so that they have the
correct cluster topology
This refers to the time period (in
milliseconds) which is used to
verify if a cluster connection
has failed to receive pings from
another server
This specifies how long a
cluster connection must stay
alive if it stops receiving
messages from a specific node
in the cluster
If the message size (in bytes) is
larger than this value then it will
be split into multiple segments
when sent over the network to
other cluster members
This specifies the time period
(milliseconds) for which a
packet sent over a cluster
connection waits (for a reply)
before throwing an exception
connector-ref
check-period
connection-ttl
min-large-message-size
call-timeout
D ef au lt
30,000 milliseconds
60,000 milliseconds
102400 bytes
30,000 milliseconds
4 81
At t rib u t e
D escrip t io n
D ef au lt
retry-interval
If the cluster connection is

created between nodes of a
cluster and the target node has
not been started, or is being
rebooted, then the cluster
connections from other nodes
will retry connecting to the
target until it comes back up.
The parameter retryinterval defines the interval
(milliseconds) between retry
attempts
This is used to increment the
retry-interval after each
retry attempt
This refers to the maximum
delay (in milliseconds) for
retries
This defines the number of
times the system will try to
connect a node on the cluster
Cluster connections use
bridges to link the nodes, and
bridges can be configured to
add a duplicate id property in
each message that is
forwarded. If the target node of
the bridge crashes and then
recovers, messages might be
resent from the source node. By
enabling duplicate detection
any duplicate messages will be
filtered out and ignored on
receipt at the target node.
This parameter determines
whether or not messages will be
distributed in a round robin
fashion between other nodes of
the cluster regardless of
whether there are matching or
indeed any consumers on other
nodes
This determines how messages
are load balanced to other
HornetQ serves which are
connected to this server
The size (in bytes) of the
window used for sending
confirmations from the server
connected to
This is used when a call is
made during a failover attempt
500 milliseconds
retry-intervalmultiplier
max-retry-interval
reconnect-attempts
use-duplicate-detection
forward-when-noconsumers
max-hops
confirmation-windowsize
call-failover-timeout
4 82
2000 milliseconds
-1 (infinite retries)
True
False
-1
1048576
-1 (no timeout)
At t rib u t e
D escrip t io n
D ef au lt
This determines how often (in

1000 milliseconds
milliseconds) the cluster
connection must broadcast
itself when attaching to the
cluster
notification-attempts
This defines as to how many
2
times the cluster connection
must broadcast itself when
connecting to the cluster
discovery-group-ref
This parameter determines
which discovery group is used
to obtain the list of other
servers in the cluster which the
current cluster connection will
make connections to
When creating connections between nodes of a cluster to form a cluster connection, HornetQ uses a
cluster user and cluster password which is defined in server configuration files (stand al o ne. xml
and d o mai n. xml ):
notification-interval
<cluster-user>HORNETQ.CLUSTER.ADMIN.USER</cluster-user>
<cluster-password>NEW USER</cluster-password>
Warning
It is important to change the default values of these credentials to prevent remote clients from
making connections to the server using the default values.
Report a bug
18.16. High Availabilit y

18.16.1. High Availabilit y Int roduct ion
HornetQ supports the ability to continue functioning after failure of one or more of the servers. Part of
this is achieved through failover support where client connections migrate from the live server to a
backup server in the event of the live server failing. To keep the backup server current, messages are
replicated from the live server to the backup server continuously through two strategies: shared store
and replication.
There are two types of high-availability Topologies:
D ed i cated T o po l o g y: This topology comprises of two EAP servers. In the first server HornetQ
is configured as a live server. In the second server HornetQ is configured as a backup server. The
EAP server which has HornetQ configured as a backup server, acts only as a container for
HornetQ. This server is inactive and can not host deployments like EJBs, MD Bs or Servlets.
C o l l o cated T o po l o g y: This topology contains two EAP servers. Each EAP server contains
two HornetQ servers (a live server and a backup server). The HornetQ live server on first EAP
server and the HornetQ backup server on the second EAP server form a live backup pair. Whereas
the HornetQ live server on the second EAP server and the HornetQ backup server on the first EAP
server form another live backup pair.
4 83
In collocated topology, as soon as a live HornetQ server (part of live-backup pair) fails, the backup
HornetQ server takes up and becomes active. When the backup HornetQ server shuts down in case
of failback then destinations and connection factories configured in the backup server are unbound
from JND I (Java Naming and D irectory Interface).
Java Naming and D irectory Interface is shared with the other live HornetQ server (part of the other
live-backup pair). Therefore unbounding of destinations and connection factories from JND I also
unbounds destinations and connection factories for this live HornetQ server.
Important
Configuration of collocated backup servers cannot contain configuration of destinations or
connection factories.
Note
The following information references stand al o ne-ful l -ha. xml . The configuration
changes can be applied to stand al o ne-ful l -ha. xml , or any configuration files derived
from it.
Report a bug
18.16.2. About Hornet Q Shared St ores

When using a shared store, both the live and backup servers share the same, entire data directory,
using a shared file system. This includes the paging directory, journal directory, large messages,
and the binding journal. When failover occurs and the backup server takes over, it will load the
persistent storage from the shared file system. Clients can then connect to it.
This form of high-availability differs from data replication, as it requires a shared file system
accessible by both the live and backup nodes. This will usually be a high performance Storage Area
Network (SAN) of some kind.
The advantage of shared store high-availability is that no replication occurs between the live and
backup nodes. This means it does not suffer any performance penalties due to the overhead of
replication during normal operation.
The disadvantage of shared store replication is that it requires a shared file system, and when the
backup server activates it must load the journal from the shared store. This can take some time,
depending on the amount of data in the store.
If the highest performance during normal operation is required, there is access to a fast SAN, and a
slightly slower failover rate is acceptable (depending on the amount of data), shared store highavailability is recommended.
Note
HornetQ's data replication mechanism would replicate JMS data and not replicate bindings.
Report a bug
4 84
18.16.3. About Hornet Q St orage Configurat ions

HornetQ supports two different configurations for shared stores:
GFS2 on a SAN, using the ASYNCIO journal type.
NFSv4, using either the ASYNCIO or NIO journal type.
Important
NFS is supported under strict configuration guidelines outlined below.
The Red Hat Enterprise Linux NFS implementation supports both direct I/O (opening files with the
O_D IRECT flag set), and kernel based asynchronous I/O. With both of these features present, it is
possible to use NFS as a shared storage option, under strict configuration rule:
The Red Hat Enterprise Linux NFS client cache must be disabled.
Note
It is recommended that, if using NFS under the above stipulations, a highly-available NFS
configuration is used.
Report a bug
18.16.4 . About Hornet Q Journal T ypes

Two journal types are available for HornetQ:
ASYNCIO
NIO
The ASYNCIO journal type, also known as AIO, is a thin native code wrapper around the Linux
asynchronous IO library (AIO). Using native functionality can provide better performance than NIO.
This journal type is only supported on Red Hat Enterprise Linux and requires that l i bai o and the
Native Components package are installed where JBoss EAP 6 is running. See the Installation Guide for
instructions on installing the Native Components package.
Important
Check the server log after JBoss EAP 6 is started, to ensure that the native library successfully
loaded, and that the ASYNCIO journal type is being used. If the native library fails to load,
HornetQ will revert to the NIO journal type, and this will be stated in the server log.
The NIO journal type uses standard Java NIO to interface with the file system. It provides very good
performance and runs on all supported platforms.
To specify the HornetQ journal type, set the parameter <jo urnal -type> in the Messag i ng
subsystem.
4 85
Report a bug
18.16.5. Configuring Hornet Q for Dedicat ed T opology wit h Shared St ore

To configure the live and backup servers for shared store in dedicated topology, configure the
stand al o ne-X. xml files on each server to have the following:
<shared-store>true</shared-store>
<paging-directory path="${shared.directory}/paging"/>
<bindings-directory path="${shared.directory}/bindings"/>
<journal-directory path="${shared.directory}/journal"/>
<large-messages-directory path="${shared.directory}/large-messages"/>
.
.
.
...
T ab le 18.14 . H o rn et Q Servers Set u p At t rib u t es ( f o r b o t h live an d b acku p servers)
At t rib u t e
D escrip t io n
shared-store
Whether this server is using shared store or not.

D efault is false
paging-directory path
This indicates the path to the paging directory.
This path is the same for both live and backup
servers as they share this directory
bindings-directory path
This indicates the path to the binding journal.
servers as they share this journal
journal-directory path
This indicates the path to the journal directory.
servers as they share this directory
large-messages-directory path
This indicates the path to the large messages
directory. This path is the same for both live and
backup servers as they share this directory
failover-on-shutdown
Whether this server becomes active when live or
currently active backup server shuts down
The backup server must also be flagged explicitly as a backup.
<backup>true</backup>
The setup attribute exclusively for HornetQ backup server is: al l o w-fai l back. This specifies
whether the backup server will automatically shutdown if the original live server comes back up.
Report a bug
18.16.6. Hornet Q Message Replicat ion
4 86
Warning
Only persistent messages are replicated. Any non-persistent messages do not survive failover.
Message replication between a live and a backup server is achieved via network traffic as the live
and backup servers do not share the same data stores. All the journals are replicated between the
two servers as long as the two servers are within the same cluster and have the same cluster
username and password. All persistent data traffic received by the live server gets replicated to the
backup server.
When the backup server comes online, it looks for and connects to a live server to attempt
synchronization. While it is synchronizing, it is unavailable as a backup server. Synchronization
can take a long time depending on the amount of data to be synchronized and the network speed. If
the backup server comes online and no live server is available, the backup server will wait until the
live server is available in the cluster.
To enable servers to replicate data, a link must be defined between them in the stand al o ne-ful l ha. xml file. A backup server will only replicate with a live server with the same group name. The
group name must be defined in the backup-group-name parameter in the stand al o ne-ful l ha. xml file on each server.
In the event of a live server failing, the correctly configured and fully synchronized backup server
takes over its duties. The backup server will activate only if the live server has failed and the backup
server is able to connect to more than half of the servers in the cluster. If more than half of the other
servers in the cluster also fail to respond it would indicate a general network failure and the backup
server will wait to retry the connection to the live server.
To get to the original state after failover, it is necessary to start the live server and wait until it is fully
synchronized with the backup server. When this has been achieved, you can shutdown the backup
server for the original live server to activate again. This happens automatically if the allowfailback attribute is set to true.
Report a bug
18.16.7. Configuring t he Hornet Q Servers for Replicat ion

To configure the live and backup servers to be a replicating pair, configure the stand al o ne-ful l ha. xml files on each server to have the following settings:
<shared-store>false</shared-store>
<backup-group-name>NameOfLiveBackupPair</backup-group-name>
<check-for-live-server>true</check-for-live-server>
.
.
.
...
T ab le 18.15. H o rn et Q R ep licat in g Set u p At t rib u t es
4 87
At t rib u t e
D escrip t io n
shared-store
Whether this server is using shared store or not.

D efault is false.
This is the unique name which identifies a
live/backup pair that should replicate with each
other
If a replicated live server should check the
current cluster to see if there is already a live
server with the same node id. D efault is false.
Whether this backup server (if it is a backup
server) becomes the live server on a normal
server shutdown. D efault is false.
backup-group-name
check-for-live-server
failover-on-shutdown
The backup server must also be flagged explicitly as a backup.

<backup>true</backup>
T ab le 18.16 . H o rn et Q B acku p Server Set u p At t rib u t es
At t rib u t e
D escrip t io n
allow-failback
Whether this server will automatically shutdown

if the original live server comes back up. D efault
is true.
The maximum number of backup journals to
keep after failback occurs. Specifying this
attribute is only necessary if allow-failback is
true. D efault value is 2, which means that after 2
failbacks the backup server must be restarted in
order to be able to replicate journal from live
server and become backup again.
max-saved-replicated-journal-size
Report a bug
18.16.8. About High-availabilit y (HA) Failover

High-availability failover is available with either automatic client failover, or application-level failover,
through a live-backup structure. Each live server has a backup server. Only one backup per live
server is supported.
The backup server only takes over if the live server crashes and there is a failover. After the live server
has been restarted, and if the al l o w-fai l back attribute is set to true, it becomes the live server
again. When the original live server takes over, the backup server reverts to being backup for the live
server.
Important
Clustering should be enabled even if you are not using the clustering capabilities. This is
because each node of the HA cluster must have a cluster-connection to all of the other nodes,
in order to negotiate roles with the other servers.
High availability cluster topology is achieved by the live and backup server as they send information
about their connection details using IP multicasts. If IP multicasts can not be used, it is also possible
4 88
to use a static configuration of the initial connections. After the initial connection, the client is
informed about the topology. If the current connection is stale, the client establishes a new
connection to another node.
After a live server has failed and a backup server has taken over, you will need to restart the live
server and have clients fail back. To do this, restart the original live server and kill the new live server.
You can do this by killing the process itself or wait for the server to crash on its own. You can also
cause failover to occur on normal server shutdown, to enable this set the fai l o ver-o n-shutd o wn
property to true in the stand al o ne. xml configuration file:
<failover-on-shutdown>true</failover-on-shutdown>
By default, the fai l o ver-o n-shutd o wn property is set to false.
You can also force the new live server to shutdown when the old live server comes back up allowing
the original live server to take over automatically by setting the al l o w-fai l back property to true in
the stand al o ne. xml configuration file:
<allow-failback>true</allow-failback>
In replication HA mode, to force the new live server to shutdown when the old live server comes back,
set the check-fo r-l i ve-server property to true in stand al o ne. xml configuration file:
<check-for-live-server>true</check-for-live-server>
Report a bug
18.16.9. Deployment s on Hornet Q Backup Servers

In a dedicated HA environment, a JBoss EAP 6 server with HornetQ configured as a backup must not
be used to host any deployments which use or connect to the HornetQ backup on that server. This
includes deployments such as Enterprise Java Beans (Stateless Session Beans, Message D riven
Beans), or servlets.
If a JBoss EAP 6 server has a HornetQ collocated backup configuration (where in the messaging
subsystem there is a HornetQ server configured as 'live' and another HornetQ server configured as
backup), then the JBoss EAP 6 server can host deployments as long as they are configured to
connect to the 'live' HornetQ server.
Report a bug
18.16.10. Hornet Q Failover Modes

HornetQ defines two types of client failover:
Automatic client failover
Application-level client failover
HornetQ provides transparent automatic reattachment of connections to the same server, for
example, in case of transient network problems. This is similar to failover, except it is reconnecting to
the same server.
D uring failover, if the client has consumers on any non persistent or temporary queues, those
queues are automatically recreated during failover on the backup node, since the backup node does
not have any information about non persistent queues.
4 89
Report a bug
18.16.11. Aut omat ic Client Failover

HornetQ clients can be configured to receive information about live and backup servers, this
information helps in event of client connection failure - live server connection, the client detects
failover and reconnects to the backup server. The backup server automatically recreates any
sessions and consumers that existed on each connection before failover, thus saving the user from
having to hand-code manual reconnection logic.
HornetQ clients detect connection failure if packets are not received from the server within the time
specified in cl i ent-fai l ure-check-peri o d . If the client does not receive data in time, the client
assumes the connection has failed and attempts failover. If the socket is closed by the operating
system, the server process is killed rather than the machine itself crashing, then the client immediately
initiates failover.
HornetQ clients can be configured in different ways to discover the list of live-backup server groups.
The client can be configured explicitly or use server discovery for the client to automatically discover
the list. Alternatively, the clients can explicitly connect to a specific server and download the current
servers and backups.
To enable automatic client failover, the client must be configured to allow non-zero reconnection
attempts.
By default, failover only occurs after at least one connection has been made to the live server. The
client retries connecting to the live server as specified in the reco nnect-attempts property and
fails after the specified number of attempts.
Report a bug
18.16.12. Applicat ion-Level Failover

In some cases, as per your requirement, you could handle any connection failure manually by
specifying reconnection logic in a custom failure handler. You can define this as application-level
failover, since the failover is handled at the user application level.
To implement application-level failover, if you are using JMS, you need to set an ExceptionListener
class on the JMS connection. If a connection failure is detected, the ExceptionListener class is called
by HornetQ. In your ExceptionListener, close the old JMS connections, look up for new connection
factory instances from JND I and create new connections.
If you are using the core API, then the procedure is very similar: set a FailureListener on the core
ClientSession instances.
Report a bug
18.17. Performance T uning

18.17.1. T uning Persist ence
Put the message journal on its own physical volume. If the disk is shared with other processes, for
example transaction co-ordinator, database or other journals, which are also reading and writing
from it, then this may greatly reduce performance since the disk head may be skipping between
the different files. One of the advantages of an append only journal is that disk head movement is
minimized. This advantage is lost if the disk is shared. If you are using paging or large messages,
make sure they are put on separate volumes too.
4 90
Minimum number of journal files. Set journal-min-files parameter to a number of files that
would fit your average sustainable rate. If you see new files being created on the journal data
directory too often, that is, lots of data is being persisted, you need to increase the minimal
number of files, this way the journal would reuse more files instead of creating new data files.
Journal file size. The journal file size must be aligned to the capacity of a cylinder on the disk. The
default value of 10MiB should be enough on most systems.
Use AIO journal. For Linux operating system, keep your journal type as AIO . AIO will scale better
than Java NIO.
Tune journal-buffer-timeout. The timeout can be increased to increase throughput at the
expense of latency.
If you are running AIO you might be able to get improved performance by increasing journalmax-io parameter value. D o not change this parameter if you are running NIO.
Report a bug
18.17.2. T uning JMS

There are a few areas where some tweaks can be done if you are using the JMS API.
D isable message ID . Use the setD i sabl eMessag eID () method on the Messag eP ro d ucer
class to disable message ID s if you do not need them. This decreases the size of the message
and also avoids the overhead of creating a unique ID .
D isable message timestamp. Use the setDisableMessageTimeStamp() method on the
Messag eP ro d ucer class to disable message timestamps if you do not need them.
Avoid ObjectMessage. ObjectMessage is convenient but it comes at a cost. The body of a
ObjectMessage uses Java serialization to serialize it to bytes. The Java serialized form of even
small objects is very verbose so takes up a lot of space on the wire, also Java serialization is slow
compared to custom marshalling techniques. Only use ObjectMessage if you really cannot use
one of the other message types, that is if you do not know the type of the payload until run-time.
Avoid AUTO_ACKNOWLEDGE. AUTO_ACKNOWLEDGE mode requires an acknowledgement to be sent
from the server for each message received on the client, this means more traffic on the network. If
you can, use DUPS_OK_ACKNOWLEDGE or use CLIENT_ACKNOWLEDGE or a transacted session
and batch up many acknowledgements with one acknowledge/commit.
Avoid durable messages. By default, JMS messages are durable. If you do not need durable
messages then set them to be non-durable. D urable messages incur a lot more overhead in
persisting them to storage.
Batch many sends or acknowledgements in a single transaction. HornetQ will only require a
network round trip on the commit, not on every send or acknowledgement.
Report a bug
18.17.3. Ot her T unings

There are various places in HornetQ where we can perform some tuning:
Use Asynchronous Send Acknowledgements. If you need to send durable messages non
transactional and you need a guarantee that they have reached the server by the time the call to
send () returns, do not set durable messages to be sent blocking, instead use asynchronous
send acknowledgements to get your acknowledgements of send back in a separate stream.
4 91
Use pre-acknowledge mode. With pre-acknowledge mode, messages are acknowledged

before they are sent to the client. This reduces the amount of acknowledgement traffic on the wire.
D isable security. There is a small performance boost when you disable security by setting the
security-enabled parameter to false in stand al o ne. xml or d o mai n. xml .
D isable persistence. You can turn off message persistence altogether by setting persistenceenabled to false in stand al o ne. xml or d o mai n. xml .
Sync transactions lazily. Setting journal-sync-transactional to false in stand al o ne. xml
or d o mai n. xml gives better transactional persistent performance at the expense of some
possibility of loss of transactions on failure.
Sync non transactional lazily. Setting journal-sync-non-transactional to false in
stand al o ne. xml or d o mai n. xml gives better non-transactional persistent performance at the
expense of some possibility of loss of durable messages on failure
Send messages non blocking. Setting block-on-durable-send and block-on-nondurable-send to false in stand al o ne. xml or d o mai n. xml (if you are using JMS and JND I)
or directly on the ServerLocator. This means you do not have to wait a whole network round trip
for every message sent.
If you have very fast consumers, you can increase consumer-window-size. This effectively
disables consumer flow control.
Socket NIO vs Socket Old IO. By default HornetQ uses old (blocking) on the server and the client
side. NIO is much more scalable but can give some latency hit compared to old blocking IO. To
service many thousands of connections on the server, then you must use NIO on the server.
However, if there are no thousands of connections on the server you can keep the server
acceptors using old IO, and you may get a small performance advantage.
Use the core API not JMS. Using the JMS API you will have slightly lower performance than using
the core API, since all JMS operations need to be translated into core operations before the server
can handle them. If using the core API try to use methods that take SimpleString as much as
possible. SimpleString, unlike java. l ang . Stri ng does not require copying before it is
written to the wire, so if you re-use Si mpl eStri ng instances between calls then you can avoid
some unnecessary copying.
Report a bug
18.17.4 . T uning T ransport Set t ings

TCP buffer sizes. If you have a fast network and fast machines you may get a performance boost
by increasing the TCP send and receive buffer sizes.
Note
Some operating systems like later versions of Linux include TCP auto-tuning and setting
TCP buffer sizes manually can prevent auto-tune from working and actually give you worse
performance.
Increase limit on file handles on the server. If you expect a lot of concurrent connections on your
servers, or if clients are rapidly opening and closing connections, you must make sure the user
running the server has permission to create sufficient file handles.
4 92
This varies from operating system to operating system. On Linux systems you can increase the
number of allowable open file handles in the file /etc/securi ty/l i mi ts. co nf. For example,
add the lines
serveruser
serveruser
soft
hard
nofile
nofile
20000
20000
This would allow up to 20000 file handles to be open by the user serveruser.
Use batch-delay and set direct-deliver to false for the best throughput for very small
messages. HornetQ comes with a preconfigured connector/acceptor pair (netty-throughput)
in stand al o ne. xml or d o mai n. xml and JMS connection factory
(ThroughputConnectionFactory) in stand al o ne. xml or d o mai n. xml which can be
used to give the very best throughput, especially for small messages.
Report a bug
18.17.5. T uning t he VM
It is highly recommend to use the latest Java JVM for the best performance. Internal testing is done
using the Sun JVM, so some of these tunings may not apply to JD Ks from other providers like IBM or
JRockit
Garbage collection. For smooth server operation, it is recommended to use a parallel garbage
collection algorithm. For example, using the JVM argument -XX: + UseP aral l el G C on Sun
JD Ks.
Memory settings. Give as much memory as you can to the server. HornetQ can run in low memory
by using paging but if it can run with all queues in RAM this will improve performance. The
amount of memory you require will depend on the size and number of your queues and the size
and number of your messages. Use the JVM arguments -Xms and -Xmx to set server available
RAM. We recommend setting them to the same high value.
Aggressive options. D ifferent JVMs provide different sets of JVM tuning parameters. It is
recommended at least using -XX:+AggressiveOpts and -XX:+UseFastAccessorMethods.
You may get some mileage with the other tuning parameters depending on your operating system
platform and application usage patterns.
Report a bug
18.17.6. Avoiding Ant i-Pat t erns

Re-use connections / sessions / consumers / producers. Probably the most common messaging
anti-pattern we see is users who create a new connection/session/producer for every message
they send or every message they consume. This is a poor use of resources. These objects take
time to create and may involve several network round trips. Always re-use them.
Note
Some popular libraries such as the Spring JMS Template use these anti-patterns. If you are
using Spring JMS Template, you may get poor performance. The Spring JMS Template can
only safely be used in an application server which caches JMS sessions, example, using
JCA), and only then for sending messages. It cannot be safely be used for synchronously
consuming messages, even in an application server.
4 93
Avoid fat messages. Verbose formats such as XML take up a lot of space on the wire and
performance will suffer as result. Avoid XML in message bodies if you can.
D o not create temporary queues for each request. This common anti-pattern involves the
temporary queue request-response pattern. With the temporary queue request-response pattern a
message is sent to a target and a reply-to header is set with the address of a local temporary
queue. When the recipient receives the message they process it then send back a response to the
address specified in the reply-to. A common mistake made with this pattern is to create a new
temporary queue on each message sent. This drastically reduces performance. Instead the
temporary queue should be re-used for many requests.
D o not use Message-D riven Beans for the sake of it. As soon as you start using MD Bs you are
greatly increasing the codepath for each message received compared to a straightforward
message consumer, since a lot of extra application server code is executed.
Report a bug
4 94
Chapter 19. Transaction Subsystem

19.1. T ransact ion Subsyst em Configurat ion
19.1.1. T ransact ions Configurat ion Overview
In t ro d u ct io n
The following procedures show you how to configure the transactions subsystem of JBoss EAP 6.
Section 19.1.3, Configure Your D atasource to Use JTA Transaction API
Section 19.1.4, Configure an XA D atasource
Section 19.1.2, Configure the Transaction Manager
Section 19.1.6, Configure Logging for the Transaction Subsystem
Report a bug
19.1.2. Configure t he T ransact ion Manager

You can configure the Transaction Manager (TM) using the web-based Management Console or the
command-line Management CLI. For each command or option given, the assumption is made that
you are running JBoss EAP 6 as a Managed D omain. If you use a Standalone Server or you want to
modify a different profile than d efaul t, you may need to modify the steps and commands in the
following ways.
N o t es ab o u t t h e Examp le C o mman d s
For the Management Console, the d efaul t profile is the one which is selected when you first log
into the console. If you need to modify the Transaction Manager's configuration in a different
profile, select your profile instead of d efaul t, in each instruction.
Similarly, substitute your profile for the d efaul t profile in the example CLI commands.
If you use a Standalone Server, only one profile exists. Ignore any instructions to choose a
specific profile. In CLI commands, remove the /pro fi l e= d efaul t portion of the sample
commands.
Note
In order for the TM options to be visible in the Management Console or Management CLI, the
transacti o ns subsystem must be enabled. It is enabled by default, and required for many
other subsystems to function properly, so it is very unlikely that it would be disabled.
C o n f ig u re t h e T M U sin g t h e Man ag emen t C o n so le

To configure the TM using the web-based Management Console, select the C o nfi g urati o n tab
from the top of the screen. If you use a managed domain, choose the correct profile from the
P ro fi l e selection box at the top left. Expand the C o ntai ner menu and select T ransacti o ns.
4 95
Most options are shown in the Transaction Manager configuration page. The R eco very options are
hidden by default. Click the R eco very tab to see the recovery options. Click Ed i t to edit any of the
options. Changes take effect immediately.
Click the Need Hel p? label to display in-line help text.
C o n f ig u re t h e T M u sin g t h e Man ag emen t C LI
In the Management CLI, you can configure the TM using a series of commands. The commands all
begin with /pro fi l e= d efaul t/subsystem= transacti o ns/ for a managed domain with profile
d efaul t, or /subsystem= transacti o ns for a Standalone Server.
Important
If transaction subsystem is configured to use hornetq journal as storage type for transaction
logs, then two instances of JBoss EAP is not permitted to use the same directory for storing the
journal. Application server instances can't share the same location and each has to configure
unique location for it.
T ab le 19 .1. T M C o n f ig u rat io n O p t io n s
O p t io n
D escrip t io n
C LI C o mman d
Enable Statistics
Whether to enable transaction

statistics. These statistics can
be viewed in the Management
Console in the Subsystem
Metri cs section of the
R unti me tab.
Whether to enable the
transaction status manager
(TSM) service, which is used for
out-of-process recovery.
Running an out of process
recovery manager to contact
the ActionStatusService from
different process is not
supported (it is normally
contacted in memory).
The default transaction timeout.
This defaults to 30 0 seconds.
You can override this
programmatically, on a pertransaction basis.
A relative or absolute filesystem
path where the TM object store
stores data. By default relative
to the o bject-sto rerel ati ve-to parameter's
value.

tem= transacti o ns/: wri teattri bute(name= enabl estati sti cs,val ue= true)
Enable TSM Status
D efault Timeout
Object Store Path
4 96
This configuration option is

unsupported.

tem= transacti o ns/: wri teattri bute(name= d efaul tti meo ut,val ue= 30 0 )
tem= transacti o ns/: wri teattri bute(name= o bjectsto re-path,val ue= txo bject-sto re)
Chapt er 1 9 . T ransact ion Subsyst em
O p t io n
D escrip t io n
C LI C o mman d
Object Store Path Relative To
References a global path

configuration in the domain
model. The default value is the
data directory for JBoss EAP 6,
which is the value of the
property
jbo ss. server. d ata. d i r,
and defaults to
EAP_HOME/d o mai n/d ata/ for
a Managed D omain, or
EAP_HOME/stand al o ne/d at
a/ for a Standalone Server
instance. The value of the
object store o bject-sto repath TM attribute is relative to
this path.
Specifies the name of the
socket binding used by the
Transaction Manager for
recovery and generating
transaction identifiers, when the
socket-based mechanism is
used. Refer to pro cess-i d so cket-max-po rts for more
information on unique identifier
generation. Socket bindings
are specified per server group
in the Server tab of the
Management Console.
Specifies the socket binding to
use for the Transaction Status
manager.
Whether or not the Transaction
Recovery process should listen
on a network socket. D efaults
to fal se.

tem= transacti o ns/: wri teattri bute(name= o bjectsto re-rel ati veto ,val ue= jbo ss. server. d
ata. d i r)
Socket Binding
Status Socket Binding
Recovery Listener

tem= transacti o ns/: wri teattri bute(name= so cketbi nd i ng ,val ue= txnreco very-envi ro nment)
This configuration option is

unsupported.
tem= transacti o ns/: wri teattri bute(name= reco veryl i stener,val ue= fal se)
The following options are for advanced use and can only be modified using the Management CLI. Be
cautious when changing them from the default configuration. Contact Red Hat Global Support
Services for more information.
T ab le 19 .2. Ad van ced T M C o n f ig u rat io n O p t io n s
O p t io n
D escrip t io n
C LI C o mman d
jts
Whether to use Java

Transaction Service (JTS)
transactions. D efaults to
fal se, which uses JTA
transactions only.

tem= transacti o ns/: wri teattri bute(name= jts,val ue
= fal se)
4 97
O p t io n
D escrip t io n
C LI C o mman d
node-identifier
The node identifier for the

Transaction Manager. This
option is required in the
following situations:

tem= transacti o ns/: wri teattri bute(name= no d ei d enti fi er,val ue= 1)
For JTS to JTS

communications
When two Transaction
Managers access shared
resource managers
When two Transaction
Managers access shared
object stores
The no d e-i d enti fi er must
be unique for each Transaction
Manager as it is required to
enforce data integrity during
recovery. The no d ei d enti fi er must also be
unique for JTA because
multiple nodes may interact
with the same resource
manager or share a transaction
object store.
process-id-socket-max-ports
The Transaction Manager

creates a unique identifier for
each transaction log. Two
different mechanisms are
provided for generating unique
identifiers: a socket-based
mechanism and a mechanism
based on the process identifier
of the process.
In the case of the socket-based
identifier, a socket is opened
and its port number is used for
the identifier. If the port is
already in use, the next port is
probed, until a free one is
found. The pro cess-i d so cket-max-po rts
represents the maximum
number of sockets the TM will
try before failing. The default
value is 10 .
4 98

tem= transacti o ns/: wri teattri bute(name= pro cessi d -so cket-maxpo rts,val ue= 10 )
O p t io n
D escrip t io n
C LI C o mman d
process-id-uuid
Set to true to use the process

identifier to create a unique
identifier for each transaction.
Otherwise, the socket-based
mechanism is used. D efaults to
true. Refer to pro cess-i d so cket-max-po rts for more
information. To enable
pro cess-i d -so cketbi nd i ng , set pro cess-i d uui d to fal se.
configuration to use if the
transaction manager should
use a socket-based process id.
Will be und efi ned if
pro cess-i d -uui d is true;
otherwise must be set.
Use HornetQ's journaled
storage mechanisms instead of
file-based storage, for the
transaction logs. This is
disabled by default, but can
improve I/O performance. It is
not recommended for JTS
transactions on separate
Transaction Managers. When
changing this option, the server
has to be restarted using the
shutd o wn command for the
change to take effect.

tem= transacti o ns/: wri teattri bute(name= pro cessi d -uui d ,val ue= true)
process-id-socket-binding
use-hornetq-store

tem= transacti o ns/: wri teattri bute(name= pro cessi d -so cketbi nd i ng ,val ue= true)

tem= transacti o ns/: wri teattri bute(name= useho rnetq sto re,val ue= fal se)
Report a bug
19.1.3. Configure Your Dat asource t o Use JT A T ransact ion API

Su mmary
This task shows you how to enable Java Transaction API (JTA) on your datasource.
Prereq u isit es
You must meet the following conditions before continuing with this task:
Your database or other resource must support Java Transaction API. If in doubt, consult the
documentation for your database or other resource.
Create a datasource. Refer to Section 6.3.1, Create a Non-XA D atasource with the Management
Interfaces .
Stop JBoss EAP 6.
Have access to edit the configuration files directly, in a text editor.
Pro ced u re 19 .1. C o n f ig u re t h e D at aso u rce t o u se Java T ran sact io n API
4 99
1. O p en t h e co n f ig u rat io n f ile in a t ext ed it o r.

D epending on whether you run JBoss EAP 6 in a managed domain or standalone server,
your configuration file will be in a different location.
A. Man ag ed d o main
The default configuration file for a managed domain is in
EAP_HOME/d o mai n/co nfi g urati o n/d o mai n. xml for Red Hat Enterprise Linux, and
EAP_HOME\domain\configuration\domain.xml for Microsoft Windows Server.
B. St an d alo n e server
The default configuration file for a standalone server is in
EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne. xml for Red Hat Enterprise
Linux, and EAP_HOME\standalone\configuration\standalone.xml for Microsoft
Windows Server.
2. Lo cat e t h e <d ataso urce> t ag t h at co rresp o n d s t o yo u r d at aso u rce.
The datasource will have the jnd i -name attribute set to the one you specified when you
created it. For example, the ExampleD S datasource looks like this:
<datasource jndi-name="java:jboss/datasources/ExampleDS" poolname="H2DS" enabled="true" jta="true" use-java-context="true" useccm="true">
3. Set t h e jta at t rib u t e t o true.
Add the following to the contents of your <d ataso urce> tag, as they appear in the previous
step: jta= "true"
Unless you have a specific use case (such as defining a read only datasource) Red Hat
discourages overriding the default value of jta= true. This setting indicates that the
datasource will honor the Java Transaction API and allows better tracking of connections by
the JCA implementation.
4. Save t h e co n f ig u rat io n f ile.
Save the configuration file and exit the text editor.
5. St art JB o ss EAP 6 .
Relaunch the JBoss EAP 6 server.
R esu lt :
JBoss EAP 6 starts, and your datasource is configured to use Java Transaction API.
Report a bug
19.1.4 . Configure an XA Dat asource

Prereq u isit es
Log into the Management Console.
500
1. Ad d a n ew d at aso u rce.
Add a new datasource to JBoss EAP 6. Click the XA D ataso urce tab at the top.
Note
Refer to Create an XA Datasource with the Management Interfaces section of the
Administration and Configuration Guide on the Red Hat Customer Portal for information on
how to add a new datasource to JBoss EAP 6.
2. C o n f ig u re ad d it io n al p ro p ert ies as ap p ro p riat e.

All datasource parameters are listed in Section 6.7.1, D atasource Parameters .
R esu lt
Your XA D atasource is configured and ready to use.
Report a bug
19.1.5. About T ransact ion Log Messages

To track transaction status while keeping the log files readable, use the D EBUG log level for the
transaction logger. For detailed debugging, use the T R AC E log level. Refer to Section 19.1.6,
Configure Logging for the Transaction Subsystem for information on configuring the transaction
logger.
The transaction manager can generate a lot of logging information when configured to log in the
T R AC E log level. Following are some of the most commonly-seen messages. This list is not
comprehensive, so you may see other messages than these.
T ab le 19 .3. T ran sact io n St at e C h an g e
Transaction Begin
When a transaction begins, the following code

is executed:
com.arjuna.ats.arjuna.coordinator
.BasicAction::Begin:1342
tsLogger.logger.trace("BasicActio
n::Begin() for action-id "+
get_uid());
501
Transaction Commit
When a transaction commits, the following code

is executed:
.BasicAction::End:1342
n::End() for action-id "+
get_uid());
Transaction Rollback
When a transaction rolls back, the following

code is executed:
.BasicAction::Abort:1575
n::Abort() for action-id "+
get_uid());
Transaction Timeout
When a transaction times out, the following code

is executed:
.TransactionReaper::doCancellatio
ns:349
tsLogger.logger.trace("Reaper
Worker " + Thread.currentThread()
+ " attempting to cancel " +
e._control.get_uid());
You will then see the same thread rolling back
the transaction as shown above.
Report a bug
19.1.6. Configure Logging for t he T ransact ion Subsyst em

Su mmary
Use this procedure to control the amount of information logged about transactions, independent of
other logging settings in JBoss EAP 6. The main procedure shows how to do this in the web-based
Management Console. The Management CLI command is given afterward.
Pro ced u re 19 .2. C o n f ig u re t h e T ran sact io n Lo g g er U sin g t h e Man ag emen t C o n so le
1. N avig at e t o t h e Lo g g in g co n f ig u rat io n area.
502
In the Management Console, click the C o nfi g urati o n tab. If you use a managed domain,
choose the server profile you wish to configure, from the P ro fi l e selection box at the top
left.
Expand the C o re menu, and select Lo g g i ng .
2. Ed it t h e co m. arjuna at t rib u t es.
Select the Lo g C ateg o ri es tab. Select co m. arjuna and lick Ed i t in the D etai l s
section. This is where you can add class-specific logging information. The co m. arjuna
class is already present. You can change the log level and whether to use parent handlers.
Lo g Level
The log level is WAR N by default. Because transactions can produce a large
quantity of logging output, the meaning of the standard logging levels is slightly
different for the transaction logger. In general, messages tagged with levels at a
lower severity than the chosen level are discarded.
T ran sact io n Lo g g in g Levels, f ro m Mo st t o Least Verb o se
TRACE
D EBUG
INFO
WARN
ERROR
FAILURE
U se Paren t H an d lers
Whether the logger should send its output to its parent logger. The default behavior
is true.
3. Changes take effect immediately.
Report a bug
19.2. T ransact ion Administ rat ion

19.2.1. Browse and Manage T ransact ions
The Management CLI supports the ability to browse and manipulate transaction records. This
functionality is provided by the interaction between the Transaction Manager and the management
API of JBoss EAP 6.
The Transaction Manager stores information about each pending transaction and the participants
involved the transaction, in a persistent storage called the object store. The management API exposes
the object store as a resource called the l o g -sto re. An API operation called pro be reads the
transaction logs and creates a node for each log. You can call the pro be command manually,
whenever you need to refresh the l o g -sto re. It is normal for transaction logs to appear and
disappear quickly.
503
Examp le 19 .1. R ef resh t h e Lo g St o re

This command refreshes the log store for server groups which use the profile d efaul t in a
managed domain. For a standalone server, remove the pro fi l e= d efaul t from the command.
/profile=default/subsystem=transactions/log-store=log-store/:probe
Examp le 19 .2. View All Prep ared T ran sact io n s

To view all prepared transactions, first refresh the log store (see Example 19.1, Refresh the Log
Store ), then run the following command, which functions similarly to a filesystem l s command.
ls /profile=default/subsystem=transactions/log-store=logstore/transactions
Each transaction is shown, along with its unique identifier. Individual operations can be run
against an individual transaction (see Manage a Transaction).
Man ag e a T ran sact io n

View a t ran sact io n ' s at t rib u t es.
To view information about a transaction, such as its JND I name, EIS product name and
version, or its status, use the : read -reso urce CLI command.
/profile=default/subsystem=transactions/log-store=logstore/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:readresource
View t h e p art icip an t s o f a t ran sact io n .
Each transaction log contains a child element called parti ci pants. Use the read reso urce CLI command on this element to see the participants of the transaction.
Participants are identified by their JND I names.
/profile=default/subsystem=transactions/log-store=logstore/transactions=0\:ffff7f000001\:b66efc2\:4f9e6f8f\:9/participants=java\:\/JmsXA:read-resource
The result may look similar to this:
{
"result" => {
"eis-product-name" => "HornetQ",
"eis-product-version" => "2.0",
"jndi-name" => "java:/JmsXA",
"status" => "HEURISTIC",
"type" => "/StateManager/AbstractRecord/XAResourceRecord"
}
}
504
The outcome status shown here is in a HEUR IST IC state and is eligible for recovery. See
Recover a transaction. for more details.
In special cases it is possible to create orphan records in the object store, that is
XAResourceRecords, which do not have any corresponding transaction record in the log.
For example, XA resource prepared but crashed before the TM recorded and is inaccessible
for the domain management API. To access such records you need to set management
option expo se-al l -l o g s to true. This option is not saved in management model and is
restored to fal se when the server is restarted.
/profile=default/subsystem=transactions/log-store=log-store:writeattribute(name=expose-all-logs, value=true)
D elet e a t ran sact io n .
Each transaction log supports a : d el ete operation, to delete the transaction log
representing the transaction.
/profile=default/subsystem=transactions/log-store=logstore/transactions=0\:ffff7f000001\:-b66efc2\:4f9e6f8f\:9:delete
R eco ver a t ran sact io n .
Each transaction participant supports recovery via the : reco ver CLI command.
/profile=default/subsystem=transactions/log-store=logstore/transactions=0\:ffff7f000001\:b66efc2\:4f9e6f8f\:9/participants=2:recover
R eco very o f h eu rist ic t ran sact io n s an d p art icip an t s
If the transaction's status is HEUR IST IC , the recovery operation changes the state to
P R EP AR E and triggers a recovery.
If one of the transaction's participants is heuristic, the recovery operation tries to replay
the co mmi t operation. If successful, the participant is removed from the transaction log.
You can verify this by re-running the : pro be operation on the l o g -sto re and
checking that the participant is no longer listed. If this is the last participant, the
transaction is also deleted.
R ef resh t h e st at u s o f a t ran sact io n wh ich n eed s reco very.
If a transaction needs recovery, you can use the : refresh CLI command to be sure it still
requires recovery, before attempting the recovery.
/profile=default/subsystem=transactions/log-store=logstore/transactions=0\:ffff7f000001\:b66efc2\:4f9e6f8f\:9/participants=2:refresh
View T ran sact io n St at ist ics
If Transaction Manager statistics are enabled, you can view statistics about the Transaction
Manager and transaction subsystem. See Section 19.1.2, Configure the Transaction Manager for
information about how to enable Transaction Manager statistics.
505
You can view statistics either via the management console or the Management CLI. In the
management console, transaction statistics are available via R u n t ime St at u s Su b syst ems
T ran sact io n s. Transaction statistics are available for each server in a managed domain. To
view the status of a different server, select C hang e Server in the left-hand menu and select the
server from the list.
The following table shows each available statistic, its description, and the Management CLI
command to view the statistic.
T ab le 19 .4 . T ran sact io n Su b syst em St at ist ics
St at ist ic
D escrip t io n
Total
The total number of

transactions processed by the
Transaction Manager on this
server.
Committed
Aborted
Timed Out
506
The number of committed

server.
The number of aborted

server.
The number of timed out

server.
C LI C o mman d
/host=master/server=
serverone/subsystem=transac
tions/:readattribute(name=numbe
r-oftransactions,include
-defaults=true)
r-of-committedtransactions,include
-defaults=true)
r-of-abortedtransactions,include
-defaults=true)
r-of-timed-outtransactions,include
-defaults=true)
St at ist ic
D escrip t io n
Heuristics
Not available in the

Management Console. Number
of transactions in a heuristic
state.
In-Flight Transactions
Failure Origin - Applications
Failure Origin - Resources
Not available in the

Management Console. Number
of transactions which have
begun but not yet terminated.
The number of failed

transactions whose failure
origin was an application.
The number of failed

transactions whose failure
origin was a resource.
C LI C o mman d
r-ofheuristics,includedefaults=true)
r-of-inflighttransactions,include
-defaults=true)
r-of-applicationrollbacks,includedefaults=true)
r-of-resourcerollbacks,includedefaults=true)
507
St at ist ic
D escrip t io n
Participant ID
The ID of the participant.
C LI C o mman d
tions/log-store=logstore/transactions=0
\:ffff7f000001\:b66efc2\:4f9e6f8f\:9:
read-childrennames(childtype=participants)
List of all transactions
The complete list of

transactions.
tions/log-store=logstore:read-childrennames(childtype=transactions)
Report a bug
19.3. T ransact ion References

19.3.1. JBoss T ransact ions Errors and Except ions
For details about exceptions thrown by methods of the UserT ransacti o n class, see the
UserTransaction API specification at
http://docs.oracle.com/javaee/6/api/javax/transaction/UserTransaction.html.
Report a bug
19.3.2. Limit at ions on JT A T ransact ions

JTA transactions are not fully transaction distribution aware across multiple instances of JBoss EAP
6. In the current implementation, transaction context is passed along the remote EJB calls. However,
this works only for simple scenarios where one server calls another server. If there are multiple
servers connecting to the transaction distribution, the context propagation is not completely safe.
For full transaction distribution support behavior, you must use JTS transactions. You must
configure the ORB in order to use JTS transactions, which includes:
enabling transactions in the JacORB subsystem;
configuring the Transaction subsystem to use JTS transactions;
calling EJB by using IIOP protocol.
Section 19.4.3, Configure the ORB for JTS Transactions
Report a bug
508
19.4 . ORB Configurat ion

19.4 .1. About Common Object Request Broker Archit ect ure (CORBA)
Common Object Request Broker Architecture (CORBA) is a standard that enables applications and
services to work together even when they are written in multiple, otherwise-incompatible, languages
or hosted on separate platforms. CORBA requests are brokered by a server-side component called
an Object Request Broker (ORB). JBoss EAP 6 provides an ORB instance, by means of the JacORB
component.
The ORB is used internally for Java Transaction Service (JTS) transactions, and is also available for
use by your own applications.
Report a bug
19.4 .2. JacORB Configurat ion
Note
In a managed domain, the JacORB subsystem is available in ful l and ful l -ha profiles
only. In a standalone server, it is available when you use the stand al o ne-ful l . xml or
stand al o ne-ful l -ha. xml configurations.
JacORB properties are most easily configured using the Management CLI. Some attributes are set in
the subsystem directly, and others must be set at the system level.
To view the settings that can be configured directly in the subsystem, use the following Management
CLI command:
/subsystem=jacorb:read-resource(include-runtime=true, recursive=true)
The current settings will be listed:
"add-component-via-interceptor" => "on",
"cache-poa-names" => "off",
"cache-typecodes" => "off",
"chunk-custom-rmi-valuetypes" => "on",
"client-requires" => "None",
"client-supports" => "MutualAuth",
"client-timeout" => 0,
"comet" => "off",
"export-corbaloc" => "on",
"giop-minor-version" => 2,
"indirection-encoding-disable" => "off",
"iona" => "off",
"lax-boolean-encoding" => "off",
"max-managed-buf-size" => 24,
"max-server-connections" => 2147483647,
"max-threads" => 32,
"monitoring" => "off",
"name" => "JBoss",
"outbuf-cache-timeout" => -1,
"outbuf-size" => 2048,
509
"pool-size" => 5,
"print-version" => "off",
"properties" => undefined,
"queue-max" => 100,
"queue-min" => 10,
"queue-wait" => "off",
"retries" => 5,
"retry-interval" => 500,
"root-context" => "JBoss/Naming/root",
"security" => "identity",
"security-domain" => undefined,
"server-requires" => "None",
"server-supports" => "MutualAuth",
"server-timeout" => 0,
"socket-binding" => "jacorb",
"ssl-socket-binding" => "jacorb-ssl",
"strict-check-on-tc-creation" => "off",
"sun" => "on",
"support-ssl" => "off",
"transactions" => "spec",
"use-bom" => "off",
"use-imr" => "off",
"ior-settings" => undefined
Other settings must be configured at the system level. Be aware that system-level settings are not
transparent in the JBoss EAP model and, as such, are not visible when interrogating the JacORB
subsystem specifically. They will not appear, for example, when using the jaco rb: read -reso urce
command shown above.
Use the following command examples to set JacORB attributes using system-level properties:
/systemproperty=jacorb.connection.client.pending_reply_timeout:add(value=600000
)
/system-property=jacorb.connection.client.idle_timeout:add(value=120000)
/system-property=jacorb.connection.server.timeout:add(value=300000)
/system-property=jacorb.native_char_codeset:add(value=UTF8)
/system-property=jacorb.native_wchar_codeset:add(value=UTF16)
Report a bug
19.4 .3. Configure t he ORB for JT S T ransact ions

In a default installation of JBoss EAP 6, the ORB is disabled. You can enable the ORB using the
command-line Management CLI.
Pro ced u re 19 .3. C o n f ig u re t h e O R B u sin g t h e Man ag emen t C o n so le
1. View t h e p ro f ile set t in g s.
510
Select C o nfi g urati o n from the top of the management console. If you use a managed
domain, select either the ful l or ful l -ha profile from the selection box at the top left.
2. Mo d if y t h e Ini ti al i zers Set t in g s
Expand the Subsystems menu. Expand the C o ntai ner menu and select JacO R B.
In the form that appears in the main screen, select the Ini ti al i zers tab and click the Ed i t
button.
Enable the security interceptors by setting the value of Securi ty to o n.
To enable the ORB for JTS, set the T ransacti o n Intercepto rs value to o n, rather than
the default spec.
Refer to the Need Hel p? link in the form for detailed explanations about these values. Click
Save when you have finished editing the values.
3. Ad van ced O R B C o n f ig u rat io n
Refer to the other sections of the form for advanced configuration options. Each section
includes a Need Hel p? link with detailed information about the parameters.
C o n f ig u re t h e O R B u sin g t h e Man ag emen t C LI
You can configure each aspect of the ORB using the Management CLI. The following commands
configure the initializers to the same values as the procedure above, for the Management Console.
This is the minimum configuration for the ORB to be used with JTS.
These commands are configured for a managed domain using the ful l profile. If necessary,
change the profile to suit the one you need to configure. If you use a standalone server, omit the
/pro fi l e= ful l portion of the commands.
Examp le 19 .3. En ab le t h e Secu rit y In t ercep t o rs

/profile=full/subsystem=jacorb/:write-attribute(name=security,value=on)
Examp le 19 .4 . En ab le T ran sact io n s in t h e JacO R B Su b syst em

/profile=full/subsystem=jacorb/:writeattribute(name=transactions,value=on)
Examp le 19 .5. En ab le JT S in t h e T ran sact io n Su b syst em

/profile=full/subsystem=transactions:writeattribute(name=jts,value=true)
511
Note
For JTS activation, the server must be restarted as reload is not enough.
Report a bug
19.5. JDBC Object St ore Support

19.5.1. JDBC St ore for T ransact ions
Prereq u isit es:
Transactions can use a JD BC datasource as its object store. If the database to be used is configured
for failover and recovery, this may be a better option than using disk space on an application server.
The advantages must be weighed up against the fact that a raw JD BC object store is a special object
store and may not perform as well as a file system or HornetQ journal object store.
Note
A JD BC datasource used as a Transactions object store must specify jta= "fal se" in the
d ataso urce section of the server's configuration file.
Pro ced u re 19 .4 . En ab le U se o f a JD B C D at aso u rce as a T ran sact io n s O b ject St o re

1. Set use-jd bc-sto re to true.
/subsystem= transacti o ns: wri te-attri bute(name= use-jd bc-sto re,
val ue= true)
2. Set jd bc-sto re-d ataso urce to the JND I name for the data source to use.
/subsystem= transacti o ns: wri te-attri bute(name= jd bc-sto re-d ataso urce,
val ue= java: jbo ss/d ataso urces/T ransD S)
3. Restart the JBoss EAP server for the changes to take effect.
shutd o wn --restart= true
The complete set of attributes is provided below.
T ab le 19 .5. T ran sact io n s JD B C St o re Pro p ert ies
Pro p ert y
D escrip t io n
use-jd bc-sto re
Set this to " true" to enable the JD BC store for

transactions.
The JND I name of the JD BC datasource used for
storage.
jd bc-sto re-d ataso urce
512
Pro p ert y
D escrip t io n
jd bc-acti o n-sto re-d ro p-tabl e
D rop and recreate the action store tables at launch.

Optional, defaults to " false" .
The prefix for the action store table names. Optional.
D rop and recreate the communication store tables at
launch. Optional, defaults to " false" .
The prefix for the communication store table names.
Optional.
D rop and recreate the state store tables at launch.
Optional, defaults to " false" .
The prefix for the state store table names. Optional.
jd bc-acti o n-sto re-tabl e-prefi x

jd bc-co mmuni cati o n-sto re-d ro ptabl e
jd bc-co mmuni cati o n-sto retabl e-prefi x
jd bc-state-sto re-d ro p-tabl e
jd bc-state-sto re-tabl e-prefi x
See Also :
Section 19.1.3, Configure Your D atasource to Use JTA Transaction API

Report a bug
513
Chapter 20. Mail subsystem

20.1. Use cust om t ransport s in mail subsyst em
When using a standard mail server (POP3, IMAP) the server has a set of attributes that can be
defined, some of which are required.
The most important of these is the o utbo und -so cket-bi nd i ng -ref which is a reference to the
outbound mail socket binding and is defined with the host address and port number.
This is not the most effective solution for some users as their host configuration used multiple hosts
for load balancing purposes. This configuration, however, is not supported by standard JavaMail
requiring some users to implement custom mail transports.
These custom transports do not require the o utbo und -so cket-bi nd i ng -ref and allow custom
host property formats.
A custom transport can be configured through the CLI using the following commands:
Pro ced u re 20.1.
1. Add new mail session. The command below creates new session called mySession and sets
JND I to java: jbo ss/mai l /MySessi o n:
/subsystem=mail/mail-session=mySession:add(jndiname=java:jboss/mail/MySession)
2. Add an outbound socket binding. The command below adds a socket binding named mysmtp-binding which points to l o cal ho st: 25.
/socket-binding-group=standard-sockets/remote-destination-outboundsocket-binding=my-smtp-binding:add(host=localhost, port=25)
3. Add an SMTP server with o utbi nd -so cket-bi nd i ng -ref. The command below adds an
SMTP called my-smtp-bi nd i ng and defines a username, password and TLS configuration.
/subsystem=mail/mail-session=mySession/server=smtp:add(outboundsocket-binding-ref= my-smtp-binding, username=user, password=pass,
tls=true)
4. Repeat this process for POP3 and IMAP:
/socket-binding-group=standard-sockets/remote-destination-outboundsocket-binding=my-pop3-binding:add(host=localhost, port=110)
/subsystem=mail/mail-session=mySession/server=pop3:add(outboundsocket-binding-ref=my-pop3-binding, username=user, password=pass)
/socket-binding-group=standard-sockets/remote-destination-outboundsocket-binding=my-imap-binding:add(host=localhost, port=143)
514
Chapt er 2 0 . Mail subsyst em
/subsystem=mail/mail-session=mySession/server=imap:add(outboundsocket-binding-ref=my-imap-binding, username=user, password=pass)

5. To use a custom server, create a new custom mail server without an outbound socket binding
(as it is optional) and instead provide the host information as part of properties.
/subsystem=mail/mailsession=mySession/custom=myCustomServer:add(username=user,password=p
ass, properties={"host" => "myhost", "my-property" =>"value"})
When defining custom protocols, any property name that contains a dot (.) is considered to
be a fully-qualified name and passed as it is supplied. Any other format (my-property, for
example) will be translated into the following format: mai l . server-name. my-property.
Below is an example complete configuration XML configuration that highlights a custom format in the
custom-server attribute:
<subsystem xmlns="urn:jboss:domain:mail:1.1">
<mail-session jndi-name="java:/Mail" from="user.name@ domain.org">
<smtp-server outbound-socket-binding-ref="mail-smtp" tls="true">
<login name="user" password="password"/>
</smtp-server>
<pop3-server outbound-socket-binding-ref="mail-pop3"/>
<imap-server outbound-socket-binding-ref="mail-imap">
<login name="nobody" password="password"/>
</imap-server>
</mail-session>
<mail-session debug="true" jndi-name="java:jboss/mail/Default">
<smtp-server outbound-socket-binding-ref="mail-smtp"/>
</mail-session>
<mail-session debug="true" jndi-name="java:jboss/mail/Custom">
<custom-server name="smtp">
<login name="username" password="password"/>
<property name="host" value="mail.example.com"/>
</custom-server>
<custom-server name="pop3" outbound-socket-binding-ref="mailpop3">
<property name="custom_prop" value="some-custom-propvalue"/>
<property name="some.fully.qualified.property" value="fullyqualified-prop-name"/>
</custom-server>
</mail-session>
<mail-session debug="true" jndi-name="java:jboss/mail/Custom2">
<custom-server name="pop3" outbound-socket-binding-ref="mailpop3">
<property name="custom_prop" value="some-custom-propvalue"/>
</custom-server>
</mail-session>
</subsystem>
Report a bug
515
Chapter 21. Enterprise JavaBeans

21.1.1. Overview of Ent erprise JavaBeans
Enterprise JavaBeans (EJB) 3.1 is an API for developing distributed, transactional, secure and
portable Java EE applications through the use of server-side components called Enterprise Beans.
Enterprise Beans implement the business logic of an application in a decoupled manner that
encourages reuse. Enterprise JavaBeans 3.1 is documented as the Java EE specification JSR-318.
JBoss EAP 6 has full support for applications built using the Enterprise JavaBeans 3.1 specification.
Report a bug
21.1.2. Overview of Ent erprise JavaBeans for Administ rat ors

JBoss administrators have many configuration options available to them to control the performance
of Enterprise Beans in JBoss EAP 6. These options can be accessed using the Management Console
or the command line configuration tool. Editing the XML server configuration file to apply changes is
also possible but not recommended.
The EJB configuration options are located in slightly different places in the Management Console
depending on how the server is being run.
1. Click on the C o nfi g urati o n tab at the top of the Management Console.
2. If you are running in D omain mode, select a profile from the P ro fi l es drop down menu on
the top left.
3. Expand the Subsystems menu.
4. Expand the C o ntai ner menu, then select EJB 3.
Report a bug
21.1.3. Ent erprise Beans

Enterprise beans are server-side application components as defined in the Enterprise JavaBeans
(EJB) 3.1 specification, JSR-318. Enterprise beans are designed for the implementation of
application business logic in a decoupled manner to encourage reuse.
Enterprise beans are written as Java classes and annotated with the appropriate EJB annotations.
They can be deployed to the application server in their own archive (a JAR file) or be deployed as
part of a Java EE application. The application server manages the lifecycle of each enterprise bean
and provides services to them such as security, transactions, and concurrency management.
An enterprise bean can also define any number of business interfaces. Business interfaces provide
greater control over which of the bean's methods are available to clients and can also allow access
to clients running in remote JVMs.
There are three types of Enterprise Bean: Session beans, Message-driven beans and Entity beans.
516
Chapt er 2 1 . Ent erprise JavaBeans
Important
Entity beans are now deprecated in EJB 3.1 and Red Hat recommends the use of JPA entities
instead. Red Hat only recommends the use of Entity beans for backwards compatibility with
legacy systems.
Report a bug
21.1.4 . Session Beans

Session Beans are Enterprise Beans that encapsulate a set of related business processes or tasks
and are injected into the classes that request them. There are three types of session bean: stateless,
stateful, and singleton.
Report a bug
21.1.5. Message-Driven Beans

Message-driven Beans (MD Bs) provide an event driven model for application development. The
methods of MD Bs are not injected into or invoked from client code but are triggered by the receipt of
messages from a messaging service such as a Java Messaging Service (JMS) server. The Java EE 6
specification requires that JMS is supported but other messaging systems can be supported as well.
Report a bug
21.2. Configuring Bean Pools

21.2.1. Bean Pools
JBoss EAP 6 maintains a number of instances of deployed stateless enterprise beans in memory to
provide faster performance. This technique is called bean pooling. When a bean is required the
application server can take one from the appropriate pool of already available beans instead of
instantiating a new one. When the bean is no longer required it is returned to the pool for reuse.
Bean pools are configured and maintained separately for stateless session beans and for messagedriven beans.
@ o rg . jbo ss. ejb3. anno tati o n. P o o l annotation can be used on EJBs to identify the pool,
which has to be used for that EJB. This annotation points to the name of that pool.
Report a bug
21.2.2. Creat e a Bean Pool

Bean pools can be created using the Management Console and the CLI tool.
Bean pools can also be created by adding the required bean pool configuration to the server
configuration file using a text editor. Example 21.2, XML Configuration Sample is an example of
what this configuration looks like.
Pro ced u re 21.1. C reat e a b ean p o o l u sin g t h e Man ag emen t C o n so le
517
1. Login to the Management Console. Refer to Section 3.3.2, Log in to the Management
Console .
2. Click on the C o n f ig u rat io n tab at the top of the screen. Expand the C o n t ain er menu and
select EJB 3. Select the B ean Po o ls tab.
3. Click Ad d . The Ad d EJB3 Bean P o o l s dialog appears.
4. Specify the required details, Name, Max P o o l Si ze, T i meo ut value, and T i meo ut unit.
5. Click Save button to finish.
Pro ced u re 21.2. C reat e a b ean p o o l u sin g t h e C LI
1. Launch the CLI tool and connect to your server. Refer to Section 3.4.4, Connect to a
Managed Server Instance Using the Management CLI .
2. Use the ad d operation with the following syntax.
/subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:add(maxpool-size=MAXSIZE, timeout=TIMEOUT, timeout-unit="UNIT")
Replace BEANPOOLNAME with the required name for the bean pool.
Replace MAXSIZE with the maximum size of the bean pool.
Replace TIMEOUT
Replace UNIT with the required time unit. Allowed values are: NANO SEC O ND S,
MIC R O SEC O ND S, MILLISEC O ND S, SEC O ND S, MINUT ES, HO UR S, and D AY S.
3. Use the read -reso urce operation to confirm the creation of the bean pool.
/subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:readresource
Examp le 21.1. C reat e a B ean Po o l u sin g t h e C LI

[standalone@ localhost:9999 /] /subsystem=ejb3/strict-max-bean-instancepool=ACCTS_BEAN_POOL:add(max-pool-size=500, timeout=5000, timeoutunit="SECONDS")
Examp le 21.2. XML C o n f ig u rat io n Samp le

<subsystem xmlns="urn:jboss:domain:ejb3:1.2">
<pools>
<bean-instance-pools>
<strict-max-pool
name="slsb-strict-max-pool" max-pool-
size="20"
instance-acquisition-timeout="5"
518
instance-acquisition-timeout-unit="MINUTES" />
<strict-max-pool name="mdb-strict-max-pool" max-poolsize="20"
instance-acquisition-timeout="5"
instance-acquisition-timeout-unit="MINUTES" />
</bean-instance-pools>
</pools>
</subsystem>
Report a bug
21.2.3. Remove a Bean Pool

Unused bean pools can be removed using the Management Console.
Prereq u isit es:
The bean pool that you want to remove cannot be in use. Refer to Section 21.2.5, Assign Bean
Pools for Session and Message-D riven Beans to ensure that it is not being used.
Pro ced u re 21.3. R emo ve a b ean p o o l u sin g t h e Man ag emen t C o n so le
1. Login to the Management Console. Refer to Section 3.3.2, Log in to the Management
Console .
3. Select the bean pool to remove in the list.
4. Click R emo ve. The R emo ve Item dialog appears.
5. Click C o nfi rm to confirm.
Pro ced u re 21.4 . R emo ve a b ean p o o l u sin g t h e C LI
2. Use the remo ve operation with the following syntax.
/subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:remove
Examp le 21.3. R emo vin g a B ean Po o l u sin g t h e C LI

[standalone@ localhost:9999 /] /subsystem=ejb3/strict-max-bean-instancepool=ACCTS_BEAN_POOL:remove
519
Report a bug
21.2.4 . Edit a Bean Pool

Bean pools can be edited using the Management Console.
Pro ced u re 21.5. Ed it a b ean p o o l u sin g t h e Man ag emen t C o n so le
1. Login to the Management Console. Section 3.3.2, Log in to the Management Console
3. Select the bean pool you want to edit.
4. Click Ed i t.
5. Edit the details you want to change. Only Max P o o l Si ze, T i meo ut value, and T i meo ut
Uni t can be changed.
Pro ced u re 21.6 . Ed it a b ean p o o l u sin g t h e C LI
2. Use the wri te-attri bute operation with the following syntax for each attribute of the bean
pool to be changed.
/subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:writeattribute(name="ATTRIBUTE", value="VALUE")
Replace ATTRIBUTE with the name of the attribute to be edited. The attributes that can be
edited in this way are max-po o l -si ze, ti meo ut, and ti meo ut-uni t.
Replace VALUE with the required value of the attribute.
3. Use the read -reso urce operation to confirm the changes to the bean pool.
/subsystem=ejb3/strict-max-bean-instance-pool=BEANPOOLNAME:readresource
Examp le 21.4 . Set t h e T imeo u t Valu e o f a B ean Po o l u sin g t h e C LI

[standalone@ localhost:9999 /] /subsystem=ejb3/strict-max-bean-instancepool=HSBeanPool:write-attribute(name="timeout", value="1500")
Report a bug
520
21.2.5. Assign Bean Pools for Session and Message-Driven Beans

JBoss Administrators can assign individual bean pools for use by session beans and messagedriven beans. Bean pools can be assigned by using the Management Console or the Management
CLI.
By default, two bean pools are provided, sl sb-stri ct-max-po o l and md b-stri ct-max-po o l
for stateless session beans and message-driven beans respectively.
To create or edit bean pools, refer to Section 21.2.2, Create a Bean Pool and Section 21.2.4, Edit a
Bean Pool .
Additionally, the @ P o o l annotation can be used on EJBs to identify the pool to be used for that EJB.
Note
Using the @ P o o l annotation on a particular EJB will override any default settings specified
using the management interfaces.
Pro ced u re 21.7. Assig n B ean Po o ls f o r Sessio n an d Messag e- D riven B ean s u sin g t h e
select EJB 3. Select the C o n t ain er tab.
3. Click Ed i t.
4. Select the bean pool to use for each type of bean from the appropriate combo-box.
Pro ced u re 21.8. Assig n B ean Po o ls f o r Sessio n an d Messag e- D riven B ean s u sin g t h e
C LI
2. Use the wri te-attri bute operation with the following syntax.
/subsystem=ejb3:write-attribute(name="BEANTYPE", value="BEANPOOL")
Replace BEANTYPE with d efaul t-md b-i nstance-po o l for Message-D riven Beans or
d efaul t-sl sb-i nstance-po o l for stateless session beans.
Replace BEANPOOL with the name of the bean pool to assign.
3. Use the read -reso urce operation to confirm the changes.
/subsystem=ejb3:read-resource
Examp le 21.5. Assig n a B ean Po o l f o r Sessio n B ean s u sin g t h e C LI
521
[standalone@ localhost:9999 /] /subsystem=ejb3:writeattribute(name="default-slsb-instance-pool", value="LV_SLSB_POOL")

Examp le 21.6 . XML C o n f ig u rat io n Samp le

<session-bean>
<stateless>
<bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>
</stateless>
<stateful default-access-timeout="5000" cache-ref="simple"/>
<singleton default-access-timeout="5000"/>
</session-bean>
<mdb>
<resource-adapter-ref resource-adapter-name="hornetq-ra"/>
<bean-instance-pool-ref pool-name="mdb-strict-max-pool"/>
</mdb>
</subsystem>
Pro ced u re 21.9 . Assig n a B ean Po o l f o r a Sessio n o r Messag e- D riven B ean u sin g t h e
@ P o o l an n o t at io n
1. Add the @ P o o l annotation to the bean and specify the name of the bean pool to be used.
@ Stateless
@ Pool("slsb-strict-max-pool")
public class HelloBean implements HelloBeanRemote {
This will override any default settings created in the management interfaces.
2. The @ o rg . jbo ss. ejb3. anno tati o n. P o o l annotation is part of the JBoss EJB3
External API and must be added as a dependency. If you are using Maven, the following
dependency should be added to your po m. xml file:
<dependency>
<groupId>org.jboss.ejb3</groupId>
<artifactId>jboss-ejb3-ext-api</artifactId>
<version>2.1.0</version>
</dependency>
Report a bug
21.3. Configuring EJB T hread Pools

21.3.1. Ent erprise Bean T hread Pools
JBoss EAP 6 maintains number of instances of Java thread objects in memory for use by enterprise
bean services, including remote invocation, the timer service, and asynchronous invocation.
522
This technique is called thread pooling. It provides improved performance by eliminating the
overhead of thread creation and gives the system administrator a mechanism for controlling resource
usage.
Multiple thread pools can be created with different parameters and each service can be allocated a
different thread pool.
Report a bug
21.3.2. Creat e a T hread Pool

EJB Thread pools can be created using the Management Console or the CLI.
Pro ced u re 21.10. C reat e an EJB T h read Po o l u sin g t h e Man ag emen t C o n so le
select EJB 3. Select the T h read Po o ls tab.
3. Click Ad d . The Ad d EJB3 T hread P o o l s dialog appears.
4. Specify the required details, Name, Max. T hread s, and Keep-Al i ve T i meo ut value.
Pro ced u re 21.11. C reat e a T h read Po o l u sin g t h e C LI
2. Use the ad d operation with the following syntax.
/subsystem=ejb3/thread-pool=THREADPOOLNAME:add(max-threads=MAXSIZE,
keepalive-time={"time"=>"TIME", "unit"=>UNIT"})
Replace THREADPOOLNAME with the required name for the thread pool.
Replace MAXSIZE with the maximum size of the thread pool.
Replace UNIT with the required time unit to be used for the required keep-alive time.
Allowed values are: NANO SEC O ND S, MIC R O SEC O ND S, MILLISEC O ND S, SEC O ND S,
MINUT ES, HO UR S, and D AY S.
Replace TIME with the integer value of the required keep-alive time. This value is a number
of UNITs.
3. Use the read -reso urce operation to confirm the creation of the bean pool.
/subsystem=ejb3/strict-max-bean-instance-pool=THREADPOOLNAME:readresource
Examp le 21.7. C reat e a T h read Po o l u sin g t h e C LI
523
[standalone@ localhost:9999 /] /subsystem=ejb3/threadpool=testmepool:add(max-threads=50, keepalive-time={"time"=>"150",

"unit"=>"SECONDS"})

<thread-pools>
<thread-pool name="default" max-threads="20" keepalivetime="150"/>
</thread-pools>
</subsystem>
Report a bug
21.3.3. Remove a T hread Pool

Unused EJB thread pools can be removed using the Management Console.
Prereq u isit es
The thread pool that you want to remove cannot be in use. Refer to the following tasks to ensure
that the thread pool is not in use:
Section 21.6.2, Configure the EJB3 Timer Service
Section 21.7.2, Configure the EJB3 Asynchronous Invocation Service Thread Pool
Section 21.8.2, Configure the EJB3 Remote Service
Pro ced u re 21.12. R emo ve an EJB t h read p o o l u sin g t h e Man ag emen t C o n so le
1. Login to the Management Console. Section 3.3.2, Log in to the Management Console .
3. Select the thread pool to you want to remove.
4. Click R emo ve. The R emo ve Item dialog appears.
5. Click C o nfi rm.
Pro ced u re 21.13. R emo ve a t h read p o o l u sin g t h e C LI
2. Use the remo ve operation with the following syntax.
/subsystem=ejb3/thread-pool=THREADPOOLNAME:remove
524
Replace THREADPOOLNAME with the name of the thread pool.
Examp le 21.9 . R emo vin g a T h read Po o l u sin g t h e C LI

[standalone@ localhost:9999 /] /subsystem=ejb3/threadpool=ACCTS_THREADS:remove
Report a bug
21.3.4 . Edit a T hread Pool

JBoss Administrators can edit Thread Pools using the Management Console and the CLI.
Pro ced u re 21.14 . Ed it a T h read Po o l u sin g t h e Man ag emen t C o n so le
1. Login to the Management Console. Section 3.3.2, Log in to the Management Console .
3. Select the thread pool you want to edit.
4. Click Ed i t.
5. Edit the details you want to change. Only the T hread Facto ry, Max T hread s, Keepal i ve
T i meo ut, and Keepal i ve T i meo ut Uni t values can be edited.
Pro ced u re 21.15. Ed it a t h read p o o l u sin g t h e C LI
2. Use the wri te_attri bute operation with the following syntax for each attribute of the thread
pool to be changed.
/subsystem=ejb3/thread-pool=THREADPOOLNAME:writeattribute(name="ATTRIBUTE", value="VALUE")
Replace THREADPOOLNAME with the name of the thread pool.
Replace ATTRIBUTE with the name of the attribute to be edited. The attributes that can be
edited in this way are keepal i ve-ti me, max-thread s, and thread -facto ry.
Replace VALUE with the required value of the attribute.
3. Use the read -reso urce operation to confirm the changes to the thread pool.
/subsystem=ejb3/thread-pool=THREADPOOLNAME:read-resource
525
Important
When changing the value of the keepal i ve-ti me attribute with the CLI the required value is
an object representation. It has the following syntax.
/subsystem=ejb3/thread-pool=THREADPOOLNAME:writeattribute(name="keepalive-time", value={"time" => "VALUE","unit" =>
"UNIT"}
Examp le 21.10. Set t h e Maxsiz e Valu e o f a T h read Po o l u sin g t h e C LI

[standalone@ localhost:9999 /] /subsystem=ejb3/threadpool=HSThreads:write-attribute(name="max-threads", value="50")
Examp le 21.11. Set t h e keepal i ve-ti me T ime Valu e o f a T h read Po o l u sin g t h e C LI

[standalone@ localhost:9999 /] /subsystem=ejb3/threadpool=HSThreads:write-attribute(name="keepalive-time", value=
{"time"=>"150"})
Report a bug
21.4 . Configuring Session Beans

21.4 .1. Session Bean Access T imeout
Stateful and Singleton Session Beans have an access timeout value specified for managing
concurrent access. This value is the period of time that a request to a session bean method can be
blocked before it will timeout.
The timeout value and the time unit used can be specified using the @ javax. ejb. AccessT i meo ut
annotation on the method. It can be specified on the session bean (which applies to all the bean's
methods) and on specific methods to override the configuration for the bean.
If they are not specified JBoss EAP 6 supplies a default timeout value of 5000 milliseconds.
Refer to the Javadocs for AccessTimeout at
http://docs.oracle.com/javaee/6/api/javax/ejb/AccessTimeout.html
Report a bug
21.4 .2. Set Default Session Bean Access T imeout Values

JBoss Administrators can specify the default timeout values for Singleton and Stateful session
beans. The default timeout values can be changed using the Management Console or the CLI. The
default value is 5000 milliseconds.
526
Pro ced u re 21.16 . Set D ef au lt Sessio n B ean Access T imeo u t Valu es u sin g t h e
1. Login to the Management Console. See Section 3.3.2, Log in to the Management Console .
3. Click Ed i t. The fields in the D etai l s area can now be edited.
4. Enter the required values in the Stateful Access T i meo ut and/or Si ng l eto n Access
T i meo ut text boxes.
Pro ced u re 21.17. Set Sessio n B ean Access T imeo u t Valu es U sin g t h e C LI
/subsystem=ejb3:write-attribute(name="BEANTYPE", value=TIME)
Replace BEANTYPE with d efaul t-stateful -bean-access-ti meo ut for Stateful
Session Beans, or d efaul t-si ng l eto n-bean-access-ti meo ut for Singleton
Session Beans.
Replace TIME with the required timeout value.
Examp le 21.12. Set t in g t h e D ef au lt St at ef u l B ean Access T imeo u t valu e t o 9 000 wit h

t h e C LI
[standalone@ localhost:9999 /] /subsystem=ejb3:writeattribute(name="default-stateful-bean-access-timeout", value=9000)

<session-bean>
<stateless>
<bean-instance-pool-ref pool-name="slsb-strict-max-pool"/>
</stateless>
<stateful default-access-timeout="5000" cache-ref="simple"/>
<singleton default-access-timeout="5000"/>
</session-bean>
</subsystem>
527
Report a bug
21.4 .3. Session Bean T ransact ion T imeout

The T ransacti o nT i meo ut annotation is used to specify the transaction timeout for a given
method. The value of the annotation is the timeout used in the given unit element. It must be a positive
integer or 0. Whenever 0 is specified, the default domain configured timeout is used.
The unit element specifies the measure of the value.
Note
Specifying a measure lesser than seconds is considered an error, even when the computed
value will result in an integral number of seconds. For example:
@ T ransacti o nT i meo ut(val ue = 10 0 0 , uni t= T i meUni t. MILISEC O ND S)
Sp ecif yin g T ran sact io n T imeo u t in t h e D ep lo ymen t D escrip t o r

The trans-ti meo ut element is used to define the transaction timeout for business, home,
component, and message listener interface methods; no interface view methods; web service
endpoint methods; and timeout callback methods. The trans-ti meo ut element resides in the
urn: trans-ti meo ut namespace and is part of the standard co ntai ner-transacti o n element
as defined in the jbo ss namespace.
Examp le 21.14 . t ran s- t imeo u t XML C o n f ig u rat io n Samp le

<ejb-name>*</ejb-name>
<tx:trans-timeout>
<tx:timeout>2</tx:timeout>
<tx:unit>Seconds</tx:unit>
</tx:trans-timeout>
ejb-name can be specified to a particular EJB name, or a wildcard (*). Specifying a wildcard (*) for
the ejb-name means that this particular transaction timeout will be the default for all EJBs in the
application.
Report a bug
21.4 .4 . Configure St at eful Session Bean Cache

In JBoss EAP 6, stateful EJB cache is configured in the ejb3 subsystem of the server configuration
file. The following procedure describes how to configure stateful EJB cache and stateful timeout.
Pro ced u re 21.18. C o n f ig u re St at ef u l EJB C ach e
1. Find the <caches> element in the ejb3 subsystem of the server configuration file. Add a
<cache> element. The following example creates a cache named " my=cache" .
<cache name="my-cache" passivation-store-ref="my-cache-file"
aliases="my-custom-cache"/>
528
2. Find the <passi vati o n-sto res> element in the ejb3 subsystem of the server
configuration file. Create a <fi l e-passi vati o n-sto re> for the cache defined in the
previous step.
<file-passivation-store name="my-cache-file" idle-timeout="1260"
idle-timeout-unit="SECONDS" max-size="200"/>
3. The ejb3 subsystem configuration should now look like the following example.
...
<caches>
<cache name="simple" aliases="NoPassivationCache"/>
<cache name="passivating" passivation-store-ref="file"
aliases="SimpleStatefulCache"/>
<cache name="clustered" passivation-store-ref="infinispan"
aliases="StatefulTreeCache"/>
<cache name="my-cache" passivation-store-ref="my-cache-file"
aliases="my-custom-cache"/>
</caches>
<passivation-stores>
<file-passivation-store name="file" idle-timeout="120" idletimeout-unit="SECONDS" max-size="500"/>
<cluster-passivation-store name="infinispan" cachecontainer="ejb"/>
<file-passivation-store name="my-cache-file" idletimeout="1260" idle-timeout-unit="SECONDS" max-size="200"/>
</passivation-stores>
...
</subsystem>
The passivating cache, " my-cache" , passivates stateful session beans to the file system as
configured in the " my-cache-file" passivation store, which has the i d l e-ti meo ut, i d l eti meo ut-uni t and max-si ze options.
4. Create a jbo ss-ejb3. xml file in the EJB JAR MET A-INF/ directory. The following example
configures the EJBs to use the cache defined in the previous steps.
<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:c="urn:ejb-cache:1.0"
xsi:schemaLocation="http://www.jboss.com/xml/ns/javaee
http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd
http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/ejb-jar_3_1.xsd"
version="3.1"
impl-version="2.0">
<assembly-descriptor>
<c:cache>
<c:cache-ref>my-cache</c:cache-ref>
</c:cache>
</assembly-descriptor>
</jboss:ejb-jar>
529
5. To method to configure a timeout value depends on whether you are implementing EJB 2 or
EJB 3.
A. EJB 3 introduced annotations, so you can specify the javax. ejb. Stateful T i meo ut
annotation in the EJB code as follows.
@ StatefulTimeout(value = 1320,
unit=java.util.concurrent.TimeUnit.SECONDS)
@ Stateful
@ Remote(MyStatefulEJBRemote.class)
public class MyStatefulEJB implements MyStatefulEJBRemote {
...
}
The @ Stateful T i meo ut value can be set to one of the following.
A value of 0 means the bean is immediately eligible for removal.
A value greater than 0 indicates a timeout value in the units specified by the uni t
parameter. The default timeout unit is MINUT ES. If you are using a passivating cache
configuration and the i d l e-ti meo ut value is less than the Stateful T i meo ut
value, JBoss EAP will passivate the bean when it is idle for the i d l e-ti meo ut period
specified. The bean is then eligible for removal after the Stateful T i meo ut period
specified.
A value of -1 means the bean will never be removed due to timeout. If you are using a
passivating cache configuration and the bean is idle for i d l e-ti meo ut, JBoss EAP
will passivate the bean instance to the passi vati o n-sto re.
Values less than -1 are not valid.
B. For both EJB 2 and EJB 3, you can configure the stateful timeout in the ejb-jar. xml file.
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
version="3.1">
<enterprise-beans>
<session>
<ejb-name>HelloBean</ejb-name>
<session-type>Stateful</session-type>
<stateful-timeout>
<unit>Seconds</unit>
</stateful-timeout>
</session>
</enterprise-beans>
</ejb-jar>
C. For both EJB 2 and EJB 3, you can configure the stateful timeout in the jbo ssejb3. xml file.
<jboss:ejb-jar xmlns:jboss="http://www.jboss.com/xml/ns/javaee"
xmlns="http://java.sun.com/xml/ns/javaee"
530
xmlns:c="urn:ejb-cache:1.0"
http://www.jboss.org/j2ee/schema/jboss-ejb3-2_0.xsd
http://java.sun.com/xml/ns/javaee
version="3.1"
impl-version="2.0">
<enterprise-beans>
<session>
<ejb-name>HelloBean</ejb-name>
<session-type>Stateful</session-type>
<stateful-timeout>
<unit>Seconds</unit>
</stateful-timeout>
</session>
</enterprise-beans>
<assembly-descriptor>
<c:cache>
<c:cache-ref>my-cache</c:cache-ref>
</c:cache>
</jboss:ejb-jar>
Ad d it io n al In f o rmat io n
To disable passivation of stateful session beans, do one of the following:
If you implement stateful session beans using EJB 3 annotations, you can disable the
passivation of the stateful session bean the annotation
@ o rg . jbo ss. ejb3. anno tati o n. C ache("No P assi vati o nC ache")
If the stateful session bean is configured in the jbo ss-ejb3. xml file, set the <c: cacheref> element value to " simple" , which is the equivalent of No P assi vati o nC ache.
<c:cache-ref>simple</c:cache-ref>
EJB cache policy " LRUStatefulContextCachePolicy" has been changed in JBoss EAP 6 so it is
impossible to have 1-to-1 configuration mapping in JBoss EAP 6.
In JBoss EAP 6, you can set up the following cache properties:
Bean life time is configured using the @StatefulTimeout in EJB 3.1.
Configure passivation of a bean to disk in the ejb3 subsystem of the server configuration file
using the i d l e-ti meo ut attribute of the <fi l e-passi vati o n-sto re> element.
Configure the maximum size of the passivation store in the ejb3 subsystem of the server
configuration file using the max-si ze attribute of the <fi l e-passi vati o n-sto re>
element.
In JBoss EAP 6, you can not configure the following cache properties:
The minimum and maximum numbers in memory cache.
531
The minimum numbers in passivation store.

The *-peri o d configurations that control the frequency of cache operations.
Report a bug
21.5. Configuring Message-Driven Beans

21.5.1. Set Default Resource Adapt er for Message-Driven Beans
JBoss Administrators can specify the default resource adapter used by message-driven beans. The
default resource adapter can be specified using the Management Console and the CLI. The default
resource adapter supplied with JBoss EAP 6 is ho rnetq -ra.
Pro ced u re 21.19 . Set t h e D ef au lt R eso u rce Ad ap t er f o r Messag e- D riven B ean s u sin g
t h e Man ag emen t C o n so le
3. Click Ed i t. The fields in the D etai l s area can now be edited.
4. Enter the name of the resource adapter to be used in the D efaul t R eso urce Ad apter text
box.
Pro ced u re 21.20. Set t h e D ef au lt R eso u rce Ad ap t er f o r Messag e- D riven B ean s u sin g t h e
C LI
/subsystem=ejb3:write-attribute(name="default-resource-adaptername", value="RESOURCE-ADAPTER")
Replace RESOURCE-ADAPTER with name of the resource adapter to be used.
Examp le 21.15. Set t h e D ef au lt R eso u rce Ad ap t er f o r Messag e- D riven B ean s u sin g

t h e C LI
[standalone@ localhost:9999 subsystem=ejb3] /subsystem=ejb3:writeattribute(name="default-resource-adapter-name", value="EDIS-RA")
[standalone@ localhost:9999 subsystem=ejb3]
532
Examp le 21.16 . XML C o n f ig u rat io n Samp le

<mdb>
<resource-adapter-ref resource-adapter-name="hornetq-ra"/>
</mdb>
</subsystem>
Report a bug
21.6. Configuring t he EJB3 T imer Service

21.6.1. EJB3 T imer Service
The EJB3 Timer Service is a standard Java EE 6 service for scheduling the invocation of the methods
from enterprise beans. Stateless session beans, singleton session beans, and message-driven
beans can all schedule any of their methods for callback at specified times. Method callback can
occur at a specific time, after a duration, at a recurring interval, or on a calendar-based schedule.
Report a bug
21.6.2. Configure t he EJB3 T imer Service

The EJB3 Timer Service can be configured via either the Management Console or Management CLI.
You can configure the thread pool used for scheduled bean invocation, and either the directory or
datasource used to store the Timer Service data. You might change the default Timer Service
directory if faster storage is available than the default directory.
Pro ced u re 21.21. C o n f ig u re t h e EJB 3 T imer Service T h read Po o l via t h e Man ag emen t
C o n so le
Prereq u isit e
The thread pool to be used by the EJB3 Timer Service must already have been created.
1. Login to the Management Console.
select EJB 3. Select the Services tab, click on T imer Service. Click Ed it .
3. Click on the EJB3 T hread P o o l drop-down list and click on the preferred thread pool's
name.
4. Restart the JBoss EAP instance.
Pro ced u re 21.22. C o n f ig u re t h e EJB 3 T imer Service T h read Po o l via t h e Man ag emen t C LI
Note
Add the prefix /pro fi l e= PROFILE_NAME to the command for a managed domain.
533
1. Run the following Management CLI command.

/subsystem=ejb3/service=timer-service:write-attribute(name=threadpool-name,value="thread-pool-name")
Pro ced u re 21.23. C o n f ig u re t h e EJB 3 T imer Service D irect o ry via t h e Man ag emen t
C o n so le
1. Login to the Management Console.
select EJB 3. Select the Services tab, click on T imer Service. Click Ed it .
3. Enter your desired values into the P ath and R el ati ve T o fields.
4. Click Save.
Pro ced u re 21.24 . C o n f ig u re t h e EJB 3 T imer Service D irect o ry via t h e Man ag emen t C LI
1. D epending on which paths you want to change, run one or both of the following
Management CLI commands. For either path you can use a system value - for example,
${jbo ss. server. d ata. d i r}.
Note
/subsystem=ejb3/service=timer-service/file-data-store=default-filestore:write-attribute(name=path,value="path")
/subsystem=ejb3/service=timer-service/file-data-store=default-filestore:write-attribute(name=relative-to,value="relative-path")
Pro ced u re 21.25. C o n f ig u re t h e EJB 3 T imer Service t o u se a D at aso u rce via t h e
Man ag emen t C LI
From JBoss EAP 6.4 you can configure the EJB3 Timer Service to use a datasource instead of a
local directory. There is a minor performance cost to this option but it has the advantage of
decreasing risk to timer data in the event of a local storage issue.
Once the EJB3 Timer Service is configured to use a datasource, you then must either configure an
EJB deployment to use the datastore or configure it as the default for all deployments. For
instructions on how to do so, see the procedure Configure one or all EJB3 Deployments to use the
Datasource.
Prereq u isit e
534
The datasource to be used by the EJB3 Timer Service must already exist and the underlying
database must support and be configured for READ _COMMITTED or SERIALIZ ABLE isolation
mode.
Note
Run the following Management CLI command.
datastore_name - A name of your choice.
datasource_name - The name of the datasource to be used for storage.
database - either po stg resq l , mssq l , sybase, mysq l , o racl e, d b2, or hsq l .
partition_name - A name of your choice. This attribute is used to distinguish timers pertaining
to a particular server instance if multiple JBoss EAP instances share the same database for
storing EJB timers. In this case, every server instance should have its own partition name. If the
database is used by only one server instance, you can leave this attribute blank.
/subsystem=ejb3/service=timer-service/database-datastore=datastore_name:add(datasource-jndi-name='java:/datasource_name',
database='database', partition='partition_name')
Pro ced u re 21.26 . C o n f ig u re o n e o r all EJB 3 D ep lo ymen t s t o u se t h e D at aso u rce
Either configure an EJB3 deployment to use the Timer Service's datasource or configure it as the
default for all deployments.
A. To configure an EJB3 deployment to use the datasource, edit the jbo ss-ejb3. xml of the
deployment so the ti mer section looks as follows. Replace datastore_name with the name
of the datastore.
[<assembly-descriptor>
<timer:timer>
<timer:persistence-store-name>datastore_name</timer:persistencestore-name>
</timer:timer>
B. To configure the datasource as the default for all deployments, run the following Management
CLI command, then restart the JBoss EAP instance. Replace datastore_name with the name
of the datastore.
Note
[/subsystem=ejb3/service=timer-service:write-attribute(name=defaultdata-store,value=datastore_name)
535
Report a bug
21.7. Configuring t he EJB Asynchronous Invocat ion Service

21.7.1. EJB3 Asynchronous Invocat ion Service
The Asynchronous Invocation Service is an Enterprise JavaBeans container service that manages
asynchronous invocation of session bean methods. This service maintains a configurable number of
threads (a thread pool) that are allocated for asynchronous method execution.
Enterprise JavaBeans 3.1 allows for any method of a session bean (stateful, stateless or singleton) to
be annotated to permit asynchronous execution.
Report a bug
21.7.2. Configure t he EJB3 Asynchronous Invocat ion Service T hread Pool

JBoss Administrators can configure the EJB3 Asynchronous Invocation Service in the JBoss EAP 6
Management Console to use a specific thread pool.
Pro ced u re 21.27. C o n f ig u re t h e EJB 3 Asyn ch ro n o u s In vo cat io n Service t h read p o o l
select EJB 3. Select the Services tab, click on Asyn c Service.
3. Click Ed i t.
4. Select the EJB3 thread pool to use from the list. The thread pool must have been already
created.
Report a bug
21.8. Configuring t he EJB3 Remot e Invocat ion Service

21.8.1. EJB3 Remot e Service
The EJB3 Remote Service manages the remote execution of Enterprise Beans with remote business
interfaces.
Report a bug
21.8.2. Configure t he EJB3 Remot e Service

JBoss Administrators can configure the EJB3 Remote Service in the JBoss EAP 6 Management
Console. The features that can be configured are the thread pool that is used for remote bean
invocation and the connector on which the EJB3 remoting channel is registered.
Pro ced u re 21.28. C o n f ig u re t h e EJB 3 R emo t e Service
536
select EJB 3. Select the Services tab, click on R emo t e Service.
3. Click Ed i t.
4. You can select a different EJB3 thread pool used for the Remote Service if additional thread
pools have been configured. You can change the connector used to register the EJB
remoting channel.
Report a bug
21.9. Configuring EJB 2.x Ent it y Beans

21.9.1. EJB Ent it y Beans
EJB Entity Beans are a type of enterprise bean from version 2.x of the EJB specification that
represented persistent data that was maintained in a database. Entity beans have been superseded
by JPA entities and officially listed for removal (pruning) from future versions of the specification. Red
Hat does not recommend the use of Entity Beans except for backwards compatibility.
Support for Entity Beans is disabled by default in JBoss EAP 6.
Note
JBoss EAP 6.x supports EJB 2.0 and above, with the exception that EJB 2.0 deployment
descriptors only work in JBoss EAP 6.4 and above.
Report a bug
21.9.2. Cont ainer-Managed Persist ence

Container-Managed Persistence (CMP) is an application server provided service that provides data
persistence for Entity beans.
Report a bug
21.9.3. Enable EJB 2.x Cont ainer-Managed Persist ence

Container-Managed Persistence (CMP) is handled by the o rg . jbo ss. as. cmp extension. CMP is
enabled by default in the managed domain and standalone server full configurations, e.g.
stand al o ne-ful l . xml .
To enable CMP in a different configuration, add the o rg . jbo ss. as. cmp module to the list of
enabled extensions in the server configuration file.
<extensions>
<extension module="org.jboss.as.cmp"/>
</extensions>
537
Once the extension has been added, you must also add the following element in the profile's XML
configuration file under the <profile> element.
<subsystem xmlns="urn:jboss:domain:cmp:1.1"/>
To disable CMP in a server configuration, remove the extension entry for the o rg . jbo ss. as. cmp
module.
Report a bug
21.9.4 . Configure EJB 2.x Cont ainer-Managed Persist ence

The EJB 2.x Container Managed Persistence (CMP) subsystem can be configured to specify any
number of key generators. Key generators are used to generate unique keys to identify each entity
persisted by the CMP service.
Two types of key generator can be defined: UUID -based and HiLo key generators.
U U ID - b ased key g en erat o rs
A UUID -based key generator creates keys using Universally Unique Identifiers. UUID key
generators only need to have a unique name, they have no other configuration.
UUID -based key generators can be added using the CLI using the following command
syntax.
/subsystem=cmp/uuid-keygenerator=UNIQUE_NAME:add
Examp le 21.17. Ad d U U ID K ey G en erat o r

To add a UUID -based key generator with the name of uui d _i d enti ti es, use this CLI
command:
/subsystem=cmp/uuid-keygenerator=uuid_identities:add
The XML configuration created by this command is:
<subsystem xmlns="urn:jboss:domain:cmp:1.0">
<key-generators>
<uuid name="uuid_identities" />
</key-generators>
</subsystem>
H iLo K ey G en erat o rs
HiLo key generators use a database to create and store entity identity keys. HiLo Key
generators must have unique names and are configured with properties that specify the
datasource used to store the data as well as the names of the table and columns that store
the keys.
HiLo key generators can be added using the CLI using the following command syntax:
/subsystem=cmp/hilo-keygenerator=UNIQUE_NAME/:add(property=value,
property=value, ...)
538
Examp le 21.18. Ad d a H iLo K ey G en erat o r

/subsystem=cmp/hilokeygenerator=HiLoKeyGeneratorFactory:add(createtable=true,create-table-ddl="create table HILOSEQUENCES
(SEQUENCENAME varchar(50) not null, HIGHVALUES integer not
null, constraint hilo_pk primary key (SEQUENCENAME))",datasource=java:jboss/datasources/ExampleDS, idcolumn=HIGHVALUES,sequence-column=SEQUENCENAME,tablename=HILOSEQUENCES,sequence-name=general,block-size=10)
The XML configuration created by this command is:
<subsystem xmlns="urn:jboss:domain:cmp:1.1">
<key-generators>
<hilo name="HiLoKeyGeneratorFactory">
<block-size>10</block-size>
<create-table>true</create-table>
<create-table-ddl>create table HILOSEQUENCES
(SEQUENCENAME varchar(50) not null, HIGHVALUES integer not
null, constraint hilo_pk primary key (SEQUENCENAME))</createtable-ddl>
<datasource>java:jboss/datasources/ExampleDS</data-source>
<id-column>HIGHVALUES</id-column>
<sequence-column>SEQUENCENAME</sequence-column>
<sequence-name>general</sequence-name>
<table-name>HILOSEQUENCES</table-name>
</hilo>
</key-generators>
</subsystem>
Note
The block-size must be set to a value !=0, otherwise the generated PKey will not
incremented and therefore the creation of entities fail with a
D uplicateKeyException.
Note
The select-hi-ddl must be set as 'FOR UPD ATE' in case of cluster to ensure the
consistency. All databases do not support the locking feature.
Report a bug
21.9.5. CMP Subsyst em Propert ies for HiLo Key Generat ors
T ab le 21.1. C MP Su b syst em Pro p ert ies f o r H iLo K ey G en erat o rs
539
Pro p ert y
D at a
t yp e
D escrip t io n
bl o ck-si ze
create-tabl e
long
boolean
create-tabl eddl
d ata-so urce
d ro p-tabl e
i d -co l umn
sel ect-hi -d d l
string
seq uenceco l umn

seq uence-name
tabl e-name
token
The block size.

If set to T R UE, a table called tabl e-name will be created using
the contents of create-tabl e-d d l if that table is not found.
The D D L commands used to create the table specified in tabl ename if the table is not found and create-tabl e is set to T R UE.
The data source used to connect to the database.
To determine whether to drop the tables.
The ID column name.
The SQL command which will return the largest key currently
stored.
The sequence column name.
token
token
The name of the sequence.

The name of the table used to store the key information.
Report a bug
54 0
token
boolean
token
string
Chapter 22. Java Connector Architecture (JCA)

22.1.1. About t he Java EE Connect or API (JCA)
JBoss EAP 6 provides full support for the Java EE Connector API (JCA) 1.6 specification. See JSR
322: Java EE Connector Architecture 1.6 for more information about the JCA specification.
A resource adapter is a component that implements the Java EE Connector API architecture. It is
similar to a datasource object, however, it provides connectivity from an Enterprise Information
System (EIS) to a broader range of heterogenuous systems, such as databases, messaging systems,
transaction processing, and Enterprise Resource Planning (ERP) systems.
Note
Java Platform Enterprise Edition 6 comes with the javax. reso urce. cci package. The
javax. reso urce. cci package comprises the APIs that should be implemented by a
resource adapter that supports the C o mmo n C l i ent Interface (CCI).
javax. reso urce. cci . R esul tSet is a member of this package and extends
java. sq l . R esul tSet. The interface of java. sq l . R esul tSet depends on the Java
version used, and hence when using C o mmo n C l i ent Interface (CCI), all applications
should assume that only java. sq l . R esul tSet methods from Java 6 can be used for data
interaction.
Report a bug
22.1.2. Java Connect or Archit ect ure (JCA)

The Java EE Connector Architecture (JCA) defines a standard architecture for Java EE systems to
external heterogeneous Enterprise Information Systems (EIS). Examples of EISs include Enterprise
Resource Planning (ERP) systems, mainframe transaction processing (TP), databases and
messaging systems.
JCA 1.6 provides features for managing:
connections
transactions
security
life-cycle
work instances
transaction inflow
message inflow
JCA 1.6 was developed under the Java Community Process as JSR-322, http://jcp.org/en/jsr/detail?
id=313.
Alt en at ive man ag ed co n n ect io n p o o ls
54 1
JBoss EAP 6.4 features the following alternative pool implementations:

org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreArrayListManagedConnectionPool: This is
the default connection pool.
org.jboss.jca.core.connectionmanager.pool.mcp.SemaphoreConcurrentLinkedQueueManagedConnectionPool:
This connection pool sometimes provides better performance profile and is enabled by using the
system property D i ro njacamar. mcp= o rg . jbo ss. jca. co re. co nnecti o nmanag er. po o l . mcp. Semapho r
eC o ncurrentLi nked Q ueueManag ed C o nnecti o nP o o l
org.jboss.jca.core.connectionmanager.pool.mcp.LeakDumperManagedConnectionPool: This connection
pool is used only for debugging purposes. For more information about the LeakD etectorPool,
refer to www.ironjacamar.org/doc/userguide/1.2/enUS/html/ch04.html#configuration_ironjacamar_leakpool
Report a bug
22.1.3. Resource Adapt ers

A resource adapter is a deployable Java EE component that provides communication between a
Java EE application and an Enterprise Information System (EIS) using the Java Connector
Architecture (JCA) specification. A resource adapter is often provided by EIS vendors to allow easy
integration of their products with Java EE applications.
An Enterprise Information System can be any other software system within an organization. Examples
include Enterprise Resource Planning (ERP) systems, database systems, e-mail servers and
proprietary messaging systems.
A resource adapter is packaged in a Resource Adapter Archive (RAR) file which can be deployed to
JBoss EAP 6. A RAR file may also be included in an Enterprise Archive (EAR) deployment.
Report a bug
22.2. Configure t he Java Connect or Archit ect ure (JCA) Subsyst em

The JCA subsystem in the JBoss EAP 6 configuration file controls the general settings for the JCA
container and resource adapter deployments.
K ey elemen t s o f t h e JC A su b syst em
Arch ive valid at io n
This setting whether archive validation will be performed on the deployment units.
The following table describes the attributes you can set for archive validation.
T ab le 22.1. Arch ive valid at io n at t rib u t es
At t rib u t e
D ef au lt Valu e
D escrip t io n
enabl ed
fai l -o nerro r
fai l -o nwarn
true
true
Specifies whether archive validation is enabled.

Specifies whether an archive validation error
report fails the deployment.
Specifies whether an archive validation warning
report fails the deployment.
false
If an archive does not implement the Java EE Connector Architecture specification
54 2
Chapt er 2 2 . Java Connect or Archit ect ure (JCA)
If an archive does not implement the Java EE Connector Architecture specification

correctly and archive validation is enabled, an error message will display during
deployment describing the problem. For example:
Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public int
hashCode()" method.
Code: com.mycompany.myproject.ResourceAdapterImpl
Severity: ERROR
Section: 19.4.2
Description: A ResourceAdapter must implement a "public boolean
equals(Object)" method.
Code: com.mycompany.myproject.ResourceAdapterImpl
If archive validation is not specified, it is considered present and the enabl ed attribute
defaults to true.
B ean valid at io n
This setting determines whether bean validation (JSR-303) will be performed on the
deployment units.
The following table describes the attributes you can set for bean validation.
T ab le 22.2. B ean valid at io n at t rib u t es
At t rib u t e
D ef au lt Valu e
D escrip t io n
enabl ed
true
Specifies whether bean validation is enabled.
If bean validation is not specified, it is considered present and the enabl ed attribute
defaults to true.
Wo rk man ag ers
There are two types of work managers:
D ef au lt wo rk man ag er
The default work manager and its thread pools.
C u st o m wo rk man ag er
A custom work manager definition and its thread pools.
The following table describes the attributes you can set for work managers.
T ab le 22.3. Wo rk man ag er at t rib u t es
At t rib u t e
D escrip t io n
name
Specifies the name of the work manager. This is required for

custom work managers.
Thread pool for standard Work instances. Each work manager
has one short-running thread pool.
Thread pool for JCA 1.6 Work instances that set the
LO NG _R UNNING hint. Each work manager can have one
optional long-running thread pool.
sho rt-runni ng thread s

l o ng -runni ng thread s
54 3
The following table describes the attributes you can set for work manager thread pools.
T ab le 22.4 . T h read p o o l at t rib u t es
At t rib u t e
D escrip t io n
al l o w-co reti meo ut

co re-thread s
Boolean setting that determines whether core threads may time

out. The default value is false.
The core thread pool size. This must be equal to or smaller than
the maximum thread pool size.
The maximum queue length.
The maximum thread pool size.
Specifies the amount of time that pool threads should be kept
after doing work.
Reference to the thread factory .
q ueue-l eng th
max-thread
keepal i ve-ti me
thread -facto ry
B o o t st rap co n t ext s
Used to define custom bootstrap contexts.

The following table describes the attributes you can set for bootstrap contexts.
T ab le 22.5. B o o t st rap co n t ext at t rib u t es
At t rib u t e
D escrip t io n
name
wo rkmanag er
Specifies the name of the bootstrap context.

Specifies the name of the work manager to use for this context.
C ach ed co n n ect io n man ag er

Used for debugging connections and supporting lazy enlistment of a connection in a
transaction, tracking whether they are used and released properly by the application.
The following table describes the attributes you can set for the cached connection
manager.
T ab le 22.6 . C ach ed co n n ect io n man ag er at t rib u t es
At t rib u t e
D ef au lt Valu e
D escrip t io n
d ebug
false
erro r
false
Outputs warning on failure to explicitly close

connections.
Throws exception on failure to explicitly close
connections.
Pro ced u re 22.1. C o n f ig u re t h e JC A su b syst em u sin g t h e Man ag emen t C o n so le

The JCA subsystem of JBoss EAP 6 can be configured in the Management Console. The JCA
configuration options are located in slightly different places in the Management Console depending
on how the server is being run.
1. Click on the C o n f ig u rat io n tab at the top of the screen. Expand the C o n n ect o r menu and
select JC A.
2. If the server is running in D omain mode, select a profile from the P ro fi l e drop-down menu
at top left.
54 4
3. Configure the settings for the JCA subsystem using the three tabs.
a. C o mmo n C o n f ig
The C o mmo n C o nfi g tab contains settings for the cached connection manager,
archive validation and bean validation (JSR-303). Each of these is contained in their
own tab as well. These settings can be changed by opening the appropriate tab,
clicking the edit button, making the required changes, and then clicking on the save
button.
Fig u re 22.1. JC A C o mmo n C o n f ig u rat io n

b. Wo rk Man ag ers
The Wo rk Manag er tab contains the list of configured Work Managers. New Work
Managers can be added, removed, and their thread pools configured here. Each
Work Manager can have one short-running thread pool and an optional longrunning thread pool.
54 5
Fig u re 22.2. Wo rk Man ag ers

The thread pool attributes can be configured by clicking Vi ew on the selected
resource adapter.
Fig u re 22.3. Wo rk Man ag er T h read Po o ls
54 6
c. B o o t st rap C o n t ext s
The Bo o tstrap C o ntexts tab contains the list of configured Bootstrap Contexts.
New Bootstrap Context objects can be added, removed, and configured. Each
Bootstrap Context must be assigned a Work Manager.
Fig u re 22.4 . B o o t st rap C o n t ext s

Report a bug
22.3. Deploy a Resource Adapt er

Resource adapters can be deployed to JBoss EAP 6 using the Management CLI tool, the Web-based
Management Console, or by manually copying the files. The process is the same as other deployable
artifacts.
Pro ced u re 22.2. D ep lo y a reso u rce ad ap t er u sin g t h e Man ag emen t C LI
1. Open a command prompt for your operating system.
2. Connect to the Management CLI.
$ EAP_HOME/bin/jboss-cli.sh --connect
$ Connected to standalone controller at localhost:9999
C:\> Connected to standalone controller at localhost:9999
3. D eploy the resource adapter.
54 7
A. To deploy the resource adapter to a standalone server, enter the following at a command
line:
$ deploy path/to/resource-adapter-name.rar
B. To deploy the resource adapter to all server groups in a managed domain, enter the
following at a command line:
$ deploy path/to/resource-adapter-name.rar --all-server-groups
Pro ced u re 22.3. D ep lo y a reso u rce ad ap t er u sin g t h e Man ag emen t C o n so le
2. Click on the R unti me tab at the top of the screen. Select Manag e D epl o yments.Click Ad d .
3. Browse to the resource adapter archive and select it. Then click Next.
4. Verify the deployment names, then click Save.
5. The resource adapter archive should now appear in the list in a disabled state.
6. Enable the resource adapter.
A. In D omain mode, click Assi g n. Select which Server Groups to assign the resource
adapter to. Click Save to finish.
B. In Standalone mode, select the Application Component from the list. Click En/D i sabl e.
Click C o nfi rm on the Are Y o u Sure? dialog to enable the component.
Pro ced u re 22.4 . D ep lo y a reso u rce ad ap t er man u ally
Copy the resource adapter archive to the server deployments directory,
A. For a standalone server, copy the resource adapter archive to the
EAP_HOME/stand al o ne/d epl o yments/ directory.
B. For a managed domain, you must use the Management Console or Management CLI to deploy
the resource adapter archive to the server groups.
Report a bug
22.4 . Configure a Deployed Resource Adapt er

JBoss administrators can configure resource adapters for JBoss EAP 6 using the Management CLI
tool, the Web-based Management Console, or by manually editing the configuration the files.
Refer to the vendor document for your resource adapter for information about supported properties
and other details.
54 8
Note
In the following procedure, the command line you must type follows the
[stand al o ne@ l o cal ho st: 9 9 9 9 /] prompt. D o not type the text within the curly braces.
That is the output you should see as a result of the command, for example, {"o utco me" = >
"success"}.
Pro ced u re 22.5. C o n f ig u re a reso u rce ad ap t er u sin g t h e Man ag emen t C LI

1. Open a command prompt for your operating system.
2. Connect to the Management CLI.
$ EAP_HOME/bin/jboss-cli.sh --connect
You should see the following result output:
$ Connected to standalone controller at localhost:9999
You should see the following result output:
C:\> Connected to standalone controller at localhost:9999
3. Add the resource adapter configuration.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar:add(archive=eis.rar, transactionsupport=XATransaction)
4. Configure the server resource adapter level <config-property>.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar/config-properties=server/:add(value=localhost)
5. Configure the po rt resource adapter level <config-property>.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar/config-properties=port/:add(value=9000)
6. Add a connection definition for a managed connection factory.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resource-
54 9
adapter=eis.rar/connection-definitions=cfName:add(classname=com.acme.eis.ra.EISManagedConnectionFactory, jndiname=java:/eis/AcmeConnectionFactory)
7. Configure the name managed connection factory level <config-property>.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar/connection-definitions=cfName/configproperties=name/:add(value=Acme Inc)
8. Add an admin object.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar/admin-objects=aoName:add(classname=com.acme.eis.ra.EISAdminObjectImpl, jndiname=java:/eis/AcmeAdminObject)
9. Configure the thresho l d admin object property.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar/admin-objects=aoName/configproperties=threshold/:add(value=10)
10. Activate the resource adapter.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar:activate
11. View the newly configured and activated resource adapter.
[standalone@ localhost:9999 /] /subsystem=resource-adapters/resourceadapter=eis.rar:read-resource(recursive=true)
{
"result" => {
"archive" => "eis.rar",
"beanvalidationgroups" => undefined,
"bootstrap-context" => undefined,
"transaction-support" => "XATransaction",
"admin-objects" => {"aoName" => {
"class-name" => "com.acme.eis.ra.EISAdminObjectImpl",
"enabled" => true,
"jndi-name" => "java:/eis/AcmeAdminObject",
"use-java-context" => true,
"config-properties" => {"threshold" => {"value" => 10}}
}},
"config-properties" => {
"server" => {"value" => "localhost"},
"port" => {"value" => 9000}
550
},
"connection-definitions" => {"cfName" => {
"allocation-retry" => undefined,
"allocation-retry-wait-millis" => undefined,
"background-validation" => false,
"background-validation-millis" => undefined,
"blocking-timeout-wait-millis" => undefined,
"class-name" =>
"com.acme.eis.ra.EISManagedConnectionFactory",
"enabled" => true,
"flush-strategy" => "FailingConnectionOnly",
"idle-timeout-minutes" => undefined,
"interleaving" => false,
"jndi-name" => "java:/eis/AcmeConnectionFactory",
"max-pool-size" => 20,
"min-pool-size" => 0,
"no-recovery" => undefined,
"no-tx-separate-pool" => false,
"pad-xid" => false,
"pool-prefill" => false,
"pool-use-strict-min" => false,
"recovery-password" => undefined,
"recovery-plugin-class-name" => undefined,
"recovery-plugin-properties" => undefined,
"recovery-security-domain" => undefined,
"recovery-username" => undefined,
"same-rm-override" => undefined,
"security-application" => undefined,
"security-domain" => undefined,
"security-domain-and-application" => undefined,
"use-ccm" => true,
"use-fast-fail" => false,
"use-java-context" => true,
"use-try-lock" => undefined,
"wrap-xa-resource" => true,
"xa-resource-timeout" => undefined,
"config-properties" => {"name" => {"value" => "Acme
Inc"}}
}}
}
}
Pro ced u re 22.6 . C o n f ig u re a reso u rce ad ap t er u sin g t h e Web - b ased Man ag emen t
C o n so le
2. Click on the C o nfi g urati o n tab at the top of the screen. Expand the C o n n ect o rs menu
and select R eso urce Ad apters.
a. In D omain mode, select a P ro fi l e from the drop-down at top left.
Click Ad d .
3. Enter the archive name and choose transaction type XAT ransacti o n from the T X: dropdown box. Then click Save.
551
4. Select the P ro perti es tab. Click Ad d .

5. Enter server for the Name and the host name, for example l o cal ho st, for the Val ue. Then
click Save to finish.
6. Click Ad d again. Enter po rt for the Name and the port number, for example 9 0 0 0 , for the
Val ue. Then click Save to finish.
7. The server and po rt properties now appear in the P ro perti es panel. Click the Vi ew link
under the O pti o n column for the listed resource adapter to view the C o nnecti o n
D efi ni ti o ns.
8. Click Ad d above the Avai l abl e C o nnecti o n D efi ni ti o ns table to add a connection
definition.
9. Enter the JND I Name and the fully qualified class name of the C o nnecti o n C l ass. Then
click Save to finish.
10. Select the new Connection D efinition, the select the P ro perti es tab. Click Ad d to enter the
Key and Val ue data for this connection definition. Click Save to finish.
11. The connection definition is complete, but disabled. Select the connection definition and click
Enabl e to enable the connection definition.
12. A dialog asks R eal l y mo d i fy C o nnecti o n D efi ni ti o n?" for the JND I name. Click
C o nfi rm. The connection definition should now appear as Enabl ed .
13. Click the Ad mi n O bjects tab at the top of the page to create and configure admin objects.
Then click Ad d .
14. Enter the JND I Name and the fully qualified C l ass Name for the admin object. Then click
Save.
15. Select the P ro perti es tab, then click Ad d to add admin object properties.
16. Enter an admin object configuration property, for example thresho l d , in the Name field.
Enter the configuration property value, for example 10 , in the Val ue field. Then click Save to
save the property.
17. The admin object is complete, but disabled. Click Enabl e to enable the admin object.
18. A dialog asks R eal l y mo d i fy Ad mi n O jbect? for the JND I name. Click C o nfi rm. The
admin object should now appear as Enabl ed .
19. You must reload the server configuration to complete the process. Click on the R unti me tab.
Expand the Server menu. Select O vervi ew in the left navigation panel.
a. Reload the servers
A. In D omain mode, hover the mouse over a server group. Select R estart G ro up.
B. In Standalone mode, a R el o ad button will be available. Click R el o ad .
20. A dialog asks D o yo u want to rel o ad the server co nfi g urati o n? for the
specified server. Click C o nfi rm. The server configuration is up to date.
Pro ced u re 22.7. C o n f ig u re a reso u rce ad ap t er man u ally
1. Stop the JBoss EAP 6 server.
552
Important
You must stop the server before editing the server configuration file for your change to
be persisted on server restart.
2. Open the server configuration file for editing.
A. For a standalone server, this is the
EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne. xml file.
B. For a managed domain, this is the EAP_HOME/d o mai n/co nfi g urati o n/d o mai n. xml
file.
3. Find the urn: jbo ss: d o mai n: reso urce-ad apters subsystem in the configuration file.
4. If there are no resource adapters defined for this subsystem, first replace:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.1"/>
with this:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
<resource-adapters>

</resource-adapters>
</subsystem>
5. Replace the <! -- <reso urce-ad apter> co nfi g urati o n l i sted bel o w --> with
the XML definition for your resource adapter. The following is the XML representation of the
resource adapter configuration created using the Management CLI and Web-based
Management Console described above.
<resource-adapter id="NAME">
<archive>
eis.rar
</archive>
<transaction-support>XATransaction</transaction-support>
<config-property name="server">
localhost
</config-property>
<config-property name="port">
9000
</config-property>
<connection-definitions>
<connection-definition classname="com.acme.eis.ra.EISManagedConnectionFactory"
jndi-name="java:/eis/AcmeConnectionFactory"
pool-name="java:/eis/AcmeConnectionFactory">
<config-property name="name">
Acme Inc
553
</config-property>
</connection-definition>
</connection-definitions>
<admin-objects>
<admin-object classname="com.acme.eis.ra.EISAdminObjectImpl"
jndi-name="java:/eis/AcmeAdminObject"
pool-name="java:/eis/AcmeAdminObject">
<config-property name="threshold">
10
</config-property>
</admin-object>
</admin-objects>
</resource-adapter>
6. St art t h e server
Relaunch the JBoss EAP 6 server to start it running with the new configuration.
Report a bug
22.5. Resource Adapt er Descript or Reference

The following tables describe the resource adapter descriptor elements.
T ab le 22.7. Main elemen t s
Elemen t
D escrip t io n
bean-val i d ati o n-g ro ups

bo o tstrap-co ntext
Specifies bean validation group that should be used

Specifies the unique name of the bootstrap context that
should be used
The config-property specifies resource adapter
configuration properties.
D efine the type of transaction supported by this resource
adapter. Valid values are: No T ransacti o n,
Lo cal T ransacti o n, XAT ransacti o n
Specifies the connection definitions
Specifies the administration objects
co nfi g -pro perty

transacti o n-suppo rt
co nnecti o n-d efi ni ti o ns

ad mi n-o bjects
T ab le 22.8. B ean valid at io n g ro u p s elemen t s

Elemen t
D escrip t io n
bean-val i d ati o n-g ro up
Specifies the fully qualified class name for a bean

validation group that should be used for validation
T ab le 22.9 . C o n n ect io n d ef in it io n / ad min o b ject at t rib u t es

At t rib u t e
D escrip t io n
cl ass-name
Specifies the fully qualified class name of a managed

connection factory or admin object
Specifies the JND I name
Should the object be activated
jnd i -name
enabl ed
554
At t rib u t e
D escrip t io n
use-java-co ntext
po o l -name
use-ccm
Specifies if a java: / JND I context should be used

Specifies the pool name for the object
Enable the cached connection manager
T ab le 22.10. C o n n ect io n d ef in it io n elemen t s

Elemen t
D escrip t io n
co nfi g -pro perty
The config-property specifies managed connection factory

configuration properties.
Specifies pooling settings
Specifies XA pooling settings
Specifies security settings
Specifies time out settings
Specifies validation settings
Specifies the XA recovery settings
po o l
xa-po o l
securi ty
ti meo ut
val i d ati o n
reco very
T ab le 22.11. Po o l elemen t s
Elemen t
D escrip t io n
mi n-po o l -si ze
The min-pool-size element indicates the minimum number

of connections a pool should hold. These are not created
until a Subject is known from a request for a connection.
This default to 0
The max-pool-size element indicates the maximum number
of connections for a pool. No more than max-pool-size
connections will be created in each sub-pool. This
defaults to 20 .
Whether to attempt to prefill the connection pool. D efault is
fal se
Specifies if the min-pool-size should be considered
strictly. D efault fal se
Specifies how the pool should be flush in case of an error.
Valid values are: Fai l i ng C o nnecti o nO nl y (default),
Id l eC o nnecti o ns, Enti reP o o l
max-po o l -si ze
prefi l l
use-stri ct-mi n
fl ush-strateg y
T ab le 22.12. XA p o o l elemen t s
Elemen t
D escrip t io n
mi n-po o l -si ze
The min-pool-size element indicates the minimum number

of connections a pool should hold. These are not created
until a Subject is known from a request for a connection.
This default to 0
The max-pool-size element indicates the maximum number
of connections for a pool. No more than max-pool-size
connections will be created in each sub-pool. This
defaults to 20 .
Whether to attempt to prefill the connection pool. D efault is
fal se
Specifies if the min-pool-size should be considered
strictly. D efault fal se
max-po o l -si ze
prefi l l
use-stri ct-mi n
555
Elemen t
D escrip t io n
fl ush-strateg y
Specifies how the pool should be flush in case of an error.

Valid values are: Fai l i ng C o nnecti o nO nl y (default),
Id l eC o nnecti o ns, Enti reP o o l
The is-same-rm-override element allows one to
unconditionally set whether the
javax.transaction.xa.XAResource.isSameRM(XAResource)
returns true or fal se
An element to enable interleaving for XA connection
factories
Oracle does not like XA connections getting used both
inside and outside a JTA transaction. To workaround the
problem you can create separate sub-pools for the
different contexts
Should the Xid be padded
Should the XAResource instances be wrapped in a
org.jboss.tm.XAResourceWrapper instance
i s-same-rm-o verri d e
i nterl eavi ng
no -tx-separate-po o l s
pad -xi d
wrap-xa-reso urce
T ab le 22.13. Secu rit y elemen t s

Elemen t
D escrip t io n
appl i cati o n
Indicates that application supplied parameters (such as

from g etC o nnecti o n(user, pw)) are used to
distinguish connections in the pool.
Indicates Subject (from security domain) are used to
distinguish connections in the pool. The content of the
security-domain is the name of the JAAS security manager
that will handle authentication. This name correlates to the
JAAS l o g i n-co nfi g . xml descriptor applicationpolicy/name attribute.
Indicates that either application supplied parameters
(such as from g etC o nnecti o n(user, pw)) or Subject
(from security domain) are used to distinguish
connections in the pool. The content of the securitydomain is the name of the JAAS security manager that will
handle authentication. This name correlates to the JAAS
l o g i n-co nfi g . xml descriptor application-policy/name
attribute.
securi ty-d o mai n
securi ty-d o mai n-and appl i cati o n
T ab le 22.14 . T ime o u t elemen t s

Elemen t
D escrip t io n
bl o cki ng -ti meo ut-mi l l i s
The blocking-timeout-millis element indicates the maximum

time in milliseconds to block while waiting for a connection
before throwing an exception. Note that this blocks only
while waiting for a permit for a connection, and will never
throw an exception if creating a new connection takes an
inordinately long time. The default is 30 0 0 0 (30 seconds).
The idle-timeout-minutes elements indicates the maximum
time in minutes a connection may be idle before being
closed. The actual maximum time depends also on the
IdleRemover scan time, which is 1/2 the smallest idletimeout-minutes of any pool.
i d l e-ti meo ut-mi nutes
556
Elemen t
D escrip t io n
The allocation retry element indicates the number of times

that allocating a connection should be tried before
throwing an exception. The default is 0 .
al l o cati o n-retry-wai t-mi l l i s The allocation retry wait millis element indicates the time in
milliseconds to wait between retrying to allocate a
connection. The default is 50 0 0 (5 seconds).
xa-reso urce-ti meo ut
Passed to XAR eso urce. setT ransacti o nT i meo ut().
D efault is zero which does not invoke the setter. Specified
in seconds
al l o cati o n-retry
T ab le 22.15. Valid at io n elemen t s

Elemen t
D escrip t io n
backg ro und -val i d ati o n
An element to specify that connections should be

validated on a background thread versus being validated
prior to use
The background-validation-minutes element specifies the
amount of time, in minutes, that background validation will
run.
Whether fail a connection allocation on the first
connection if it is invalid (true) or keep trying until the pool
is exhausted of all potential connections (false). D efault is
fal se
backg ro und -val i d ati o nmi nutes

use-fast-fai l
T ab le 22.16 . Ad min o b ject elemen t s

Elemen t
D escrip t io n
co nfi g -pro perty
Specifies an administration object configuration property.
T ab le 22.17. R eco very elemen t s

Elemen t
D escrip t io n
reco ver-cred enti al
Specifies the user name / password pair or security

domain that should be used for recovery.
Specifies an implementation of the
org.jboss.jca.core.spi.recovery.RecoveryPlugin class.
reco ver-pl ug i n
The deployment schemas are defined in jbo ss-as-reso urce-ad apters_1_0 . xsd and
http://www.ironjacamar.org/doc/schema/ironjacamar_1_0.xsd for automatic activation.
Report a bug
22.6. View Defined Connect ion St at ist ics

You can read statistics for a defined connection from the d epl o yment= name. rar subtree.
Statistics are defined at this level and not at the /subsystem level as this ensures they are
accessible for any rar that is not defined in any configuration in the stand al o ne. xml or
d o mai n. xml files.
For example:
557
Examp le 22.1. View D ef in ed C o n n ect io n St at ist ics

/deployment=example.rar/subsystem=resourceadapters/statistics=statistics/connectiondefinitions=java\:\/testMe:read-resource(include-runtime=true)
Note
Ensure you specify the include-runtime=true argument, as all statistics are runtime only
information and the default is fal se.
Report a bug
22.7. Resource Adapt er St at ist ics

C o re St at ist ics
The following table contains a list of the supported resource adapter core statistics:
T ab le 22.18. C o re St at ist ics
N ame
D escrip t io n
Acti veC o unt
The number of active connections. Each of the connections is either in

use by an application or available in the pool
The number of available connections in the pool.
The average time spent blocking on obtaining an exclusive lock on the
pool. The value is in milliseconds.
The average time spent creating a connection. The value is in
milliseconds.
The number of connections created.
The number of connections destroyed.
The number of connections currently in use.
The maximum time it took to create a connection. The value is in
milliseconds.
The maximum number of connections used.
The maximum number of requests waiting for a connection at the same
time.
The maximum time spent waiting for an exclusive lock on the pool.
The number of timed out connections.
The total time spent waiting for an exclusive lock on the pool. The value is
in milliseconds.
The total time spent creating connections. The value is in milliseconds.
Avai l abl eC o unt

Averag eBl o cki ng T
i me
Averag eC reati o nT i
me
C reated C o unt
D estro yed C o unt
InUseC o unt
MaxC reati o nT i me
MaxUsed C o unt
MaxWai tC o unt
MaxWai tT i me
T i med O ut
T o tal Bl o cki ng T i m
e
T o tal C reati o nT i m
e
Wai tC o unt
The number of requests that had to wait for a connection.
Report a bug
22.8. Deploy t he WebSphere MQ Resource Adapt er

558
Ab o u t Web Sp h ere MQ
WebSphere MQ is IBM's Messaging Oriented Middleware (MOM) software that allows applications on
distributed systems to communicate with each other. This is accomplished through the use of
messages and message queues. WebSphere MQ is responsible for delivering messages to the
message queues and for transferring data to other queue managers using message channels. For
more information about WebSphere MQ, see WebSphere MQ.
Su mmary
This topic covers the steps to deploy and configure the WebSphere MQ Resource Adapter in Red Hat
JBoss Enterprise Application Platform 6. This can be accomplished by manually editing
configuration files, using the Management CLI tool, or using the web-based Management Console.
Note
There is a known issue in WebSphere MQ Resource Adapter version 7.5.0.3 and earlier that
causes periodic recovery to fail with an XA exception with messages similar to the following in
the JBoss EAP server log:
WARN [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016027: Local
XARecoveryModule.xaRecovery got XA exception
XAException.XAER_INVAL: javax.transaction.xa.XAException: The
method 'xa_recover' has failed with errorCode '-5'.
A fix is available in version 7.5.0.4. A detailed description of this issue can be found here:
http://www-01.ibm.com/support/docview.wss?uid=swg1IC97579.
Be aware that WebSphere MQ 8.0 and above is not supported in EAP 6.x.
Prereq u isit es
Before you get started, you must verify the version of the WebSphere MQ resource adapter and
understand some of the WebSphere MQ configuration properties.
The WebSphere MQ resource adapter is supplied as a Resource Archive (RAR) file called
wmq . jmsra-VERSION. rar. You must use version 7.5.0.x. See the note above for information
about the required version.
You must know the values of the following WebSphere MQ configuration properties. Refer to the
WebSphere MQ product documentation for details about these properties.
MQ.QUEUE.MANAGER: The name of the WebSphere MQ queue manager
MQ.HOST.NAME: The host name used to connect to the WebSphere MQ queue manager
MQ.CHANNEL.NAME: The server channel used to connect to the WebSphere MQ queue
manager
MQ.QUEUE.NAME: The name of the destination queue
MQ.TOPIC.NAME: The name of the destination topic
MQ.PORT: The port used to connect to the WebSphere MQ queue manager
559
MQ.CLIENT: The transport type

For outbound connections, you must also be familiar with the following configuration property:
MQ.CONNECTIONFACTORY.NAME: The name of the connection factory instance that will
provide the connection to the remote system
Note
The following are default configurations provided by IBM and are subject to change. Please
refer to WebSphere MQ documentation for more information.
Pro ced u re 22.8. D ep lo y t h e R eso u rce Ad ap t er Man u ally

1. If you need transaction support with the WebSphereMQ resource adapter, you must
repackage the wmq . jmsra-VER SIO N. rar archive to include the mq etcl i ent. jar. You
can use the following command:
[user@ host ~]$ jar -uf wmq . jmsra-VERSION. rar mq etcl i ent. jar
Be sure to replace the VERSION with the correct version number.
2. Copy the wmq . jmsra-VERSION. rar file to the EAP_HOME/stand al o ne/d epl o yments/
directory.
3. Add the resource adapter to the server configuration file.
a. Open the EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne-ful l . xml file
in an editor.
b. Find the urn: jbo ss: d o mai n: reso urce-ad apters subsystem in the
configuration file.
c. If there are no resource adapters defined for this subsystem, first replace:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.1"/>
with this:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
<resource-adapters>
 with the following:
560
<resource-adapter>
<archive>
wmq.jmsra-VERSION.rar
</archive>
<transaction-support>NoTransaction</transactionsupport>
<connection-definition
classname="com.ibm.mq.connector.outbound.ManagedConnectionFacto
ryImpl"
jndiname="java:jboss/MQ.CONNECTIONFACTORY.NAME"
pool-name="MQ.CONNECTIONFACTORY.NAME">
<config-property name="hostName">
MQ.HOST.NAME
</config-property>
MQ.PORT
</config-property>
<config-property name="channel">
MQ.CHANNEL.NAME
</config-property>
<config-property name="transportType">
MQ.CLIENT
</config-property>
<config-property name="queueManager">
MQ.QUEUE.MANAGER
</config-property>
<security>
<securitydomain>MySecurityDomain</security-domain>
</security>
<admin-objects>
<admin-object
classname="com.ibm.mq.connector.outbound.MQQueueProxy"
jndi-name="java:jboss/MQ.QUEUE.NAME"
pool-name="MQ.QUEUE.NAME">
<config-property name="baseQueueName">
MQ.QUEUE.NAME
</config-property>
<config-property name="baseQueueManagerName">
MQ.QUEUE.MANAGER
</config-property>
</admin-object>
<admin-object classname="com.ibm.mq.connector.outbound.MQTopicProxy"
jndi-name="java:jboss/MQ.TOPIC.NAME" poolname="MQ.TOPIC.NAME">
<config-property name="baseTopicName">
MQ.TOPIC.NAME
</config-property>
<config-property name="brokerPubQueueManager">
561
MQ.QUEUE.MANAGER
</config-property>
</admin-object>
</admin-objects>
</resource-adapter>
Be sure to replace the VERSION with the actual version in the name of the RAR.
B. For transactional deployments, replace the <! -- <reso urce-ad apter>
co nfi g urati o n l i sted bel o w --> with the following:
<resource-adapter>
<archive>
wmq.jmsra-VERSION.rar
</archive>
<transaction-support>XATransaction</transactionsupport>
<connection-definition
classname="com.ibm.mq.connector.outbound.ManagedConnectionFacto
ryImpl"
jndiname="java:jboss/MQ.CONNECTIONFACTORY.NAME"
pool-name="MQ.CONNECTIONFACTORY.NAME">
<config-property name="hostName">
MQ.HOST.NAME
</config-property>
MQ.PORT
</config-property>
<config-property name="channel">
MQ.CHANNEL.NAME
</config-property>
<config-property name="transportType">
MQ.CLIENT
</config-property>
<config-property name="queueManager">
MQ.QUEUE.MANAGER
</config-property>
<security>
<securitydomain>MySecurityDomain</security-domain>
</security>
<recovery>
<recover-credential>
<securitydomain>RECOVERY_SECURITY_DOMAIN</security-domain>
</recover-credential>
</recovery>
<admin-objects>
<admin-object
classname="com.ibm.mq.connector.outbound.MQQueueProxy"
562
jndi-name="java:jboss/MQ.QUEUE.NAME"
pool-name="MQ.QUEUE.NAME">
<config-property name="baseQueueName">
MQ.QUEUE.NAME
</config-property>
<config-property name="baseQueueManagerName">
MQ.QUEUE.MANAGER
</config-property>
</admin-object>
<admin-object classname="com.ibm.mq.connector.outbound.MQTopicProxy"
jndi-name="java:jboss/MQ.TOPIC.NAME" poolname="MQ.TOPIC.NAME">
<config-property name="baseTopicName">
MQ.TOPIC.NAME
</config-property>
<config-property name="brokerPubQueueManager">
MQ.QUEUE.MANAGER
</config-property>
</admin-object>
</admin-objects>
</resource-adapter>
You must also replace the USER_NAME and PASSWORD with the valid user name
and password.
Note
To support transactions, the <transaction-support> element was set to
XAT ransacti o n. To support XA recovery, the <recovery> element was
added to the connection definition.
e. If you want to change the default provider for the EJB3 messaging system in JBoss
EAP 6 from HornetQ to WebSphere MQ, modify the urn: jbo ss: d o mai n: ejb3: 1. 2
subsystem as follows:
Replace:
<mdb>
<resource-adapter-ref resource-adapter-name="hornetqra"/>
</mdb>
with:
<mdb>
<resource-adapter-ref resource-adapter-name="wmq.jmsraVERSION.rar"/>
</mdb>
563
Pro ced u re 22.9 . Mo d if y t h e MD B co d e t o u se t h e reso u rce ad ap t er
Configure the ActivationConfigProperty and ResourceAdapter in the MD B code as follows:
@ MessageDriven(name="WebSphereMQMDB", activationConfig = {
@ ActivationConfigProperty(propertyName =
"destinationType",propertyValue = "javax.jms.Queue"),
@ ActivationConfigProperty(propertyName = "useJNDI", propertyValue
= "false"),
@ ActivationConfigProperty(propertyName = "hostName", propertyValue
= "MQ.HOST.NAME"),
@ ActivationConfigProperty(propertyName = "port", propertyValue =
"MQ.PORT"),
@ ActivationConfigProperty(propertyName = "channel", propertyValue
= "MQ.CHANNEL.NAME"),
@ ActivationConfigProperty(propertyName = "queueManager",
propertyValue = "MQ.QUEUE.MANAGER"),
@ ActivationConfigProperty(propertyName = "destination",
propertyValue = "MQ.QUEUE.NAME"),
@ ActivationConfigProperty(propertyName = "transportType",
propertyValue = "MQ.CLIENT")
})
@ ResourceAdapter(value = "wmq.jmsra-VERSION.rar")
@ TransactionAttribute(TransactionAttributeType.NOT_SUPPORTED)
public class WebSphereMQMDB implements MessageListener {
}
Report a bug
22.9. Inst all JBoss Act ive MQ Resource Adapt er

To install JBoss Active MQ (A-MQ) resource adapter to JBoss EAP 6 in order to make it work with
JBoss Fuse A-MQ 6.1.0, follow the steps provided at: https://access.redhat.com/documentation/enUS/Red_Hat_JBoss_AMQ/6.1/html/Integrating_with_JBoss_Enterprise_Application_Platform/D eployRar-InstallRar.html.
Report a bug
22.10. Configure a Generic JMS Resource Adapt er for Use wit h a T hirdpart y JMS Provider
Su mmary
JBoss EAP 6 can be configured to work with third-party JMS providers, however not all JMS
providers produce a JMS JCA resource adapter for integration with Java application platforms. This
procedure covers the steps required to configure the generic JMS resource adapter included in
JBoss EAP 6 to connect to a JMS provider. In this procedure, Tibco EMS 6.3 is used as an example
JMS provider, however other JMS providers may need a different configuration.
564
Important
Before using the generic JMS resource adapter, check with the JMS provider to see if they
have their own resource adapter that can be used with JBoss EAP 6. The generic JMS JCA
resource adapter should only be used when a JMS provider does not provide its own resource
adapter.
Prereq u isit es
JMS provider server is already configured and ready for use. Any binaries required for the
provider's JMS implementation will be needed.
You will also need to know the values of the following JMS provider properties to be able to
lookup its JMS resources (connection factories, queues and topics).
java.naming.factory.initial
java.naming.provider.url
java.naming.factory.url.pkgs
In the example XML used in this procedure, these parameters are written as
P R O VID ER _FAC T O R Y _INIT IAL, P R O VID ER _UR L, and P R O VID ER _C O NNEC T IO N_FAC T O R Y
respectively. Replace these placeholders with the JMS provider values for your environment.
Pro ced u re 22.10. C o n f ig u re a G en eric JMS R eso u rce Ad ap t er f o r U se wit h a T h ird - p art y
JMS Pro vid er
1. C reat e a JB o ss Mo d u le f o r t h e JMS p ro vid er
Create a JBoss module that contains all the libraries required to connect and communicate
with the JMS provider. This module will be named o rg . jbo ss. g eneri cjms. pro vi d er.
a. Create the following directory structure:
EAP_HOME/mo d ul es/system/l ayers/base/o rg /jbo ss/g eneri cjms/pro vi d
er/mai n
b. Copy the binaries required for the provider's JMS implementation to
er/mai n.
Note
For Tibco EMS, the binaries required are ti bjms. jar and ti bcrypt. jar
from the Tibco installation's l i b directory.
c. Create a mo d ul e. xml file in
er/mai n as below, listing the JAR files from the previous steps as resources:
<module xmlns="urn:jboss:module:1.1"
name="org.jboss.genericjms.provider">
<resources>
565

<resource-root path="tibjms.jar"/>
<resource-root path="tibcrypt.jar"/>
</resources>
<dependencies>
<module name="javax.jms.api"/>
</dependencies>
</module>
2. C o n f ig u re a JN D I ext ern al co n t ext t o t h e JMS p ro vid er
The JMS resources (connection factories and destinations) are looked up in the JMS
provider. We will add an external context in the JBoss EAP 6 instance so that any local lookup
for this resource will automatically look up the resource on the remote JMS provider.
Note
In this procedure, EAP_HOME/stand al o ne/co nfi g urati o n/stand al o neful l . xml is used as the JBoss EAP 6 configuration file.
In EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne-ful l . xml , under
<subsystem xml ns= "urn: jbo ss: d o mai n: nami ng : 1. 4 ">, add:
<bindings>
<external-context name="java:global/remoteJMS/"
module="org.jboss.genericjms.provider"
class="javax.naming.InitialContext">
<environment>
<property name="java.naming.factory.initial"
value="${PROVIDER_FACTORY_INITIAL}"/>
<property name="java.naming.provider.url"
value="${PROVIDER_URL}"/>
<property name="java.naming.factory.url.pkgs"
value="${PROVIDER_URL_PKGS}"/>
</environment>
</external-context>
</bindings>
These three properties' values must be replaced by the correct value to connect to the remote
JMS provider. Take care when replacing the placeholder text to keep the ${} intact.
3. En ab le Lo o ku p b y St rin g
There are some JMS provider (such as Tibco EMS) that do not support the JND I
l o o kup(Name) method. In these cases, add the
o rg . jbo ss. as. nami ng . l o o kup. by. stri ng property with a value true to workaround
this issue.
Examp le 22.2. En ab le Lo o ku p b y St rin g wit h T ib co EMS

A complete definition for an external -co ntext to Tibco EMS would be as follows.
566
<bindings>
<external-context name="java:global/remoteJMS/"
module="org.jboss.genericjms.provider"
<environment>
value="com.tibco.tibjms.naming.TibjmsInitialContextFactory"/>
value="TIBCO_EMS_SERVER_HOST_NAME:PORT"/>
<property name="java.naming.factory.url.pkgs"
value="com.tibco.tibjms.naming"/>
<property name="org.jboss.as.naming.lookup.by.string"
value="true"/>
</environment>
</external-context>
</bindings>
With this external context, any JND I lookup to a resource starting with
java: g l o bal /remo teJMS/ will be done on the remote JMS provider (after removing this
prefix). As an example, if a Message-D riven Bean perform a JND I lookup for
java: g l o bal /remo teJMS/Q ueue1, the external context will connect to the remote JMS
provider and perform a lookup for the Q ueue1 resource.
4. C o n f ig u re t h e G en eric JMS R eso u rce Ad ap t er
In EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne-ful l . xml , add the generic
resource adapter configuration to <subsystem
xml ns= "urn: jbo ss: d o mai n: reso urce-ad apters: 1. 1">.
Examp le 22.3. T ib co EMS R eso u rce Ad ap t er C o n f ig u rat io n

A complete resource adapter definition for Tibco EMS would be as follows.
<resource-adapter id="org.jboss.genericjms">
<module slot="main" id="org.jboss.genericjms"/>
<transaction-support>NoTransaction</transaction-support>
<connection-definition classname="org.jboss.resource.adapter.jms.JmsManagedConnectionFactory"
jndi-name="java:/jms/XAQCF"
pool-name="XAQCF">
<config-property name="ConnectionFactory">
XAQCF
</config-property>
<config-property name="JndiParameters">
java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitial
ContextFactory;java.naming.provider.url=TIBCO_EMS_SERVER_HOST_NA
ME:PORT
</config-property>
<security>
<application/>
567
</security>
</resource-adapter>
5. C o n f ig u re t h e d ef au lt messag e- d riven b ean p o o l wit h t h e g en eric reso u rce

ad ap t er.
In EAP_HOME/stand al o ne/co nfi g urati o n/stand al o ne-ful l . xml , in <subsystem
xml ns= "urn: jbo ss: d o mai n: ejb3: 1. 5">, update the <md b> configuration with:
<mdb>
<resource-adapter-ref resource-adaptername="org.jboss.genericjms"/>
</mdb>
R esu lt
The generic JMS resource adapter is now configured and ready for use. When creating a new
Message-driven Bean, use code similar below to use the resource adapter.
Examp le 22.4 . U se t h e G en eric R eso u rce Ad ap t er

@ MessageDriven(name = "HelloWorldQueueMDB", activationConfig = {
// The generic JMS resource adapter requires the JNDI bindings
// for the actual remote connection factory and destination
@ ActivationConfigProperty(propertyName = "connectionFactory",
propertyValue = "java:global/remoteJMS/XAQCF"),
propertyValue = "java:global/remoteJMS/Queue1"),
@ ActivationConfigProperty(propertyName = "acknowledgeMode",
propertyValue = "Auto-acknowledge") })
public class HelloWorldQueueMDB implements MessageListener {
public void onMessage(Message message) {
// called every time a message is received from the `Queue1` queue
on the JMS provider.
}
}
568
Warning
When using the generic JMS resource adapter, ensure you set the session to be transacted, to
avoid a potential Nul l P o i nterExcepti o n (NPE) error. The NPE error occurs because the
generic JMS resource adapter attempts processing of parameters, when the Java EE
specification states that they are not to be processed.
connection.createSession(true, Session.SESSION_TRANSACTED);
Examp le 22.5. U se t h e Po o led C o n n ect io n

You can also use the pooled connection factory from the resource adapter.
@ Resource(lookup = "java:/jms/XAQCF")
private ConnectionFactory cf;
Examp le 22.6 . Perf o rm a Lo o ku p

It is not possible to inject a resource from an external context directly but it is possible to inject an
external context and then perform a lookup. For example, a lookup for a queue deployed in a
Tibco EMS broker would be as follows.
@ Resource(lookup = "java:global/remoteJMS")
private Context context;
...
Queue queue = (Queue) context.lookup("Queue1")
Report a bug
22.11. Configuring t he Hornet Q JCA Adapt er for Remot e Connect ions

Pro ced u re 22.11. C o n f ig u re an R A ad ap t er t o co n n ect t o t wo remo t e JB o ss EAP
in st an ces
Before configuring the HornetQ RA to connect to remote EAP instance, we must create two connectors
that point to remote JBoss EAP instances:
1. Create outbound socket bindings:
<outbound-socket-binding name="remote-jms-server-a">
<remote-destination
host="${remote.jms.server.one.bind.address:127.0.0.1}"
port="${remote.jms.server.one.bind.port:5445}"/>
<outbound-socket-binding name="remote-jms-server-b">
569
<remote-destination
host="${remote.jms.server.two.bind.address:127.0.0.1}"
port="${remote.jms.server.two.bind.port:5545}"/>
2. Create two netty connectors:
<netty-connector name="netty-remote-node-a" socket-binding="remotejms-server-a"/>
<netty-connector name="netty-remote-node-b" socket-binding="remotejms-server-a"/>
3. Create the RA configuration using the two netty connectors:
<pooled-connection-factory name="hornetq-remote-ra">
<inbound-config>
<use-jndi>true</use-jndi>
<jndiparams>java.naming.factory.initial=org.jboss.naming.remote.cli
ent.InitialContextFactory;java.naming.provider.url=remote://${remo
te.jms.server.one.bind.address}:4447,${remote.jms.server.two.bind.a
ddress}:4547;java.naming.security.principal=${user.name};java.namin
g.security.credentials=${user.password}</jndi-params>
</inbound-config>
<user>${user.name}</user>
<password>${user.password}</password>
<connectors>
<connector-ref connector-name="netty-remote-node-a"/>
<connector-ref connector-name="netty-remote-node-b"/>
</connectors>
<entries>
<entry name="java:/RemoteJmsXA"/>
</entries>
4. Annotate the MD B to use the resource adapter using the @ResourceAdapter annotation:
@ MessageDriven(name = "InQueueMDB", activationConfig = {
propertyValue = "${hornetq.in.queue.short}"),
propertyValue = "Auto-acknowledge"),
@ ActivationConfigProperty(propertyName = "useJNDI",propertyValue =
"true")
},mappedName = "${hornetq.inf.queue.long}")
@ ResourceAdapter("hornetq-remote-ra")
5. Run the following CLI commands to enable property substitution in order to use properties in
deployment descriptors:
/subsystem=ee:write-attribute(name=jboss-descriptor-propertyreplacement,value=true)
570
/subsystem=ee:write-attribute(name=spec-descriptor-propertyreplacement,value=true)
/subsystem=ee:write-attribute(name=annotation-propertyreplacement,value=true)
6. Create an external context to find the remote destinations in order to send message from the
MD B:
<bindings>
<external-context name="java:global/remote"
module="org.jboss.remote-naming"
<environment>
value="org.jboss.naming.remote.client.InitialContextFactory"/>
value="remote://${remote.jms.server.one.bind.address:ragga}:4447,${
remote.jms.server.two.bind.address:ragga}:4547"/>
<property name="java.naming.security.principal"
value="${user.name}"/>
<property name="java.naming.security.credentials"
value="${user.password}"/>
</environment>
</external-context>
</bindings>
7. The MD B code would look like:
@ MessageDriven(name = "InQueueMDB", activationConfig = {
propertyValue = "${hornetq.in.queue.short}"),
propertyValue = "Auto-acknowledge"),
@ ActivationConfigProperty(propertyName = "useJNDI",propertyValue =
"true"),
@ ActivationConfigProperty(propertyName = "hA", propertyValue =
"true")
},mappedName = "${hornetq.inf.queue.full}")
@ ResourceAdapter("hornetq-remote-ra")
public class InQueueMDB implements MessageListener {
private static final Logger log =
Logger.getLogger(InQueueMDB.class);
@ Resource(lookup = "java:global/remote")
private InitialContext context;
@ Resource( name = "${hornetq.jms.connection}")
private ConnectionFactory qcf;
public void onMessage(Message message){
try {
if ( message instanceof TextMessage){
Object obj = (Queue) context.lookup("/jms/queue/outQueue");
qConnection = (QueueConnection)
qcf.createConnection("quickuser","quick123+");
571
qSession = qConnection.createQueueSession(true,
Session.SESSION_TRANSACTED);
qSender = qSession.createSender(outQueue);
qSender.send(message);
8. You must remember that the hornetq RA module contains remoting-naming dependency for
the MD B code given above to work:
<module xmlns="urn:jboss:module:1.1" name="org.hornetq.ra">
<properties>
<property name="jboss.api" value="private"/>
</properties>
<resources>
<resource-root path="hornetq-ra-2.3.25.Final-redhat-1.jar"/>

</resources>
<dependencies>
<module name="org.hornetq"/>
<module name="org.jboss.as.transactions"/>
<module name="org.jboss.as.messaging"/>
<module name="org.jboss.jboss-transaction-spi"/>
<module name="org.jboss.logging"/>
<module name="org.jboss.remote-naming"/>
<module name="javax.jms.api" />
<module name="org.jboss.jts"/>
<module name="org.jboss.netty"/>
<module name="org.jgroups"/>
<module name="javax.resource.api"/>
</dependencies>
</module>
9. You must also add org.hornetq to global modules so the JMS API is visible to the application:
<global-modules>
<module name="org.jboss.common-core" slot="main"/>
<module name="org.hornetq" slot="main"/>
</global-modules>
Report a bug
572
Chapter 23. Hibernate Search

23.1. Get t ing St art ed wit h Hibernat e Search
23.1.1. About Hibernat e Search
Hibernate Search provides full-text search capability to Hibernate applications. It is especially suited
to search applications for which SQL-based solutions are not suited, including: full-text, fuzzy and
geolocation searches. Hibernate Search uses Apache Lucene as its full-text search engine, but is
designed to minimize the maintenance overhead. Once it is configured, indexing, clustering and data
synchronization is maintained transparently, allowing you to focus on meeting your business
requirements.
Report a bug
23.1.2. Overview
Hibernate Search consists of an indexing component as well as an index search component, both
are backed by Apache Lucene. Each time an entity is inserted, updated or removed in/from the
database, Hibernate Search keeps track of this event (through the Hibernate event system) and
schedules an index update. All these updates are handled without you having to interact with the
Apache Lucene APIs directly. Instead, interaction with the underlying Lucene indexes is handled via
an Ind exManag er.
Once the index is created, you can search for entities and return lists of managed entities instead of
dealing with the underlying Lucene infrastructure. The same persistence context is shared between
Hibernate and Hibernate Search. The Ful l T extSessi o n class is built on top of the Hibernate
Sessi o n class so that the application code can use the unified o rg . hi bernate. Q uery or
javax. persi stence. Q uery APIs exactly the same way an HQL, JPA-QL, or native query would
do.
Note
It is recommended - for both your database and Hibernate Search - to execute your operations
in a transaction, be it JD BC or JTA.
Note
Hibernate Search works perfectly fine in the Hibernate / EntityManager long conversation
pattern, known as atomic conversation.
Report a bug
23.1.3. About t he Index Manager

Each time an entity is inserted, updated or removed from the database, Hibernate Search keeps track
of this event through the Hibernate event system and schedules an index update. Interaction with the
underlying Lucene indexes is handled by an IndexManager, each of which is uniquely identified by
name. By default there is a one-to-one relationship between IndexManager and Lucene index. The
573
IndexManager abstracts the specific index configuration, including the selected backend, reader
strategy and the chosen DirectoryProvider.
Report a bug
23.1.4 . About t he Direct ory Provider

Apache Lucene, which is part of the Hibernate Search infrastructure, has the concept of a D irectory
for storage of indexes. Hibernate Search handles the initialization and configuration of a Lucene
D irectory instance via a Directory Provider.
The d i recto ry_pro vi d er property specifies the directory provider to be used to store the indexes.
The default filesystem directory provider is fi l esystem, which uses the local filesystem to store
indexes.
Report a bug
23.1.5. About t he Worker

Updates to Lucene indexes are handled by the Hibernate Search Worker, which receives all entity
changes, queues them by context and applies them once a context ends. The most common context
is the transaction, but may be dependent on the number of entity changes or some other application
(life cycle) events.
For better efficiency, interactions are batched and generally applied once the context ends. Outside a
transaction, the index update operation is executed right after the actual database operation. In the
case of an ongoing transaction, the index update operation is scheduled for the transaction commit
phase and discarded in case of transaction rollback. A worker may be configured with a specific
batch size limit, after which indexing occurs regardless of the context.
For details of Worker configuration options see Section 23.2.5, Worker Configuration .
There are two immediate benefits to this method of handling index updates:
Performance: Lucene indexing works better when operation are executed in batch.
ACID ity: The work executed has the same scoping as the one executed by the database
transaction and is executed if and only if the transaction is committed. This is not ACID in the
strict sense, but ACID behavior is rarely useful for full text search indexes since they can be rebuilt
from the source at any time.
The two batch modes - no scope vs transactional - are the equivalent of autocommit versus
transactional behavior. From a performance perspective, the transactional mode is recommended. The
scoping choice is made transparently. Hibernate Search detects the presence of a transaction and
adjust the scoping (see Section 23.2.5, Worker Configuration ).
Report a bug
23.1.6. Back End Set up and Operat ions

2 3.1 .6 .1 . Back End
Hibernate Search uses various back ends to process batches of work. The back end is not limited to
the configuration option d efaul t. wo rker. backend . This property specifies a implementation of
the Backend Q ueueP ro cesso r interface which is a part of a back end configuration. Additional
settings are required to set up a back end, for example the JMS back end.
574
Chapt er 2 3. Hibernat e Search
Report a bug
2 3.1 .6 .2 . Luce ne
In the Lucene mode, all index updates for a node (JVM) are executed by the same node to the Lucene
directories using the directory providers. Use this mode in a non-clustered environment or in
clustered environments with a shared directory store.
Fig u re 23.1. Lu cen e B ack En d C o n f ig u rat io n

Lucene mode targets non-clustered or clustered applications where the D i recto ry manages the
locking strategy. The primary advantage of Lucene mode is simplicity and immediate visibility of
changes in Lucene queries. The Near Real Time (NRT) back end is an alternate back end for nonclustered and non-shared index configurations.
Report a bug
2 3.1 .6 .3. JMS

Index updates for a node are sent to the JMS queue. A unique reader processes the queue and
updates the master index. The master index is subsequently replicated regularly to slave copies to
establish the master/slave pattern. The master is responsible for Lucene index updates. The slaves
accept read and write operations but process read operations on local index copies. The master is
the sole responsible for updating the Lucene index. Only the master applies the local changes in an
update operation.
575
Fig u re 23.2. JMS B acken d C o n f ig u rat io n

This mode targets clustered environments where throughput is critical and index update delays are
affordable. The JMS provider ensures reliability and uses the slaves to change the local index
copies.
Report a bug
23.1.7. Reader St rat egies

When executing a query, Hibernate Search uses a reader strategy to interact with the Apache Lucene
indexes. Choose a reader strategy based on the profile of the application (frequent updates, read
mostly, asynchronous index update, etc).
Report a bug
2 3.1 .7 .1 . T he Share d St rat e gy
576
Using the shared strategy, Hibernate Search shares the same Ind exR ead er for a given Lucene
index across multiple queries and threads provided that the Ind exR ead er remains updated. If the
Ind exR ead er is not updated, a new one is opened and provided. Each Ind exR ead er is made of
several Seg mentR ead ers. The shared strategy reopens segments that have been modified or
created after the last opening and shares the already loaded segments from the previous instance.
This is the default strategy.
Report a bug
2 3.1 .7 .2 . T he No t -share d St rat e gy

Using the no t-shared strategy, a Lucene Ind exR ead er opens every time a query executes.
Opening and starting up a Ind exR ead er is an expensive operation. As a result, opening an
Ind exR ead er for each query execution is not an efficient strategy.
Report a bug
2 3.1 .7 .3. Cust o m Re ade r St rat e gie s

You can write a custom reader strategy using an implementation of
o rg . hi bernate. search. read er. R ead erP ro vi d er. The implementation must be thread safe.
Report a bug
2 3.1 .7 .4 . Re ade r St rat e gy Co nfigurat io n

Change the strategy from the default (shared ) to no t-shared as follows:
hibernate.search.[default|<indexname>].reader.strategy = not-shared
Alternately, customize the reader strategy by replacing
my. co rp. myapp. C usto mR ead erP ro vi d er with the custom strategy implementation:
hibernate.search.[default|<indexname>].reader.strategy =
my.corp.myapp.CustomReaderProvider
Report a bug
23.2. Configurat ion

23.2.1. Minimum Configurat ion
Hibernate Search has been designed to provide flexibility in its configuration and operation, with
default values carefully chosen to suit the majority of use cases. At a minimum a D i recto ry
P ro vi d er must be configured, along with its properties. The default D irectory Provider is
fi l esystem, which uses the local filesystem for index storage. For details of available D irectory
Providers and their configuration, see Section 23.2.3, D irectoryProvider Configuration .
If you are using Hibernate directly, settings such as the D irectoryProvider must be set in the
configuration file, either hi bernate. pro perti es or hi bernate. cfg . xml . If you are using
Hibernate via JPA the configuration file is persi stence. xml .
Report a bug
577
23.2.2. Configuring t he IndexManager

Hibernate Search offers several implementations for this interface:
d i recto ry-based : the default implementation which uses the Lucene D i recto ry abstraction to
manage index files.
near-real -ti me: avoids flushing writes to disk at each commit. This index manager is also
D i recto ry based, but uses Lucene's near real-time (NRT) functionality.
To specify an IndexManager other than the default, specify the following property:
hibernate.search.[default|<indexname>].indexmanager = near-real-time
Report a bug
2 3.2 .2 .1 . Dire ct o ry-base d

The D i recto ry-based implementation is the default Ind exManag er implementation. It is highly
configurable and allows separate configurations for the reader strategy, back ends, and directory
providers.
Report a bug
2 3.2 .2 .2 . Ne ar Re al T im e
The NR T Ind exManag er is an extension of the default Ind exManag er and leverages the Lucene
NRT (Near Real Time) feature for low latency index writes. However, it ignores configuration settings
for alternative back ends other than l ucene and acquires exclusive write locks on the D i recto ry.
The Ind exWri ter does not flush every change to the disk to provide low latency. Queries can read
the updated states from the unflushed index writer buffers. However, this means that if the
Ind exWri ter is killed or the application crashes, updates can be lost so the indexes must be
rebuilt.
The Near Real Time configuration is recommended for non-clustered websites with limited data due to
the mentioned disadvantages and because a master node can be individually configured for
improved performance as well.
Report a bug
2 3.2 .2 .3. Cust o m

Specify a fully qualified class name for the custom implementation to set up a customized
Ind exManag er. Set up a no-argument constructor for the implementation as follows:
[default|<indexname>].indexmanager = my.corp.myapp.CustomIndexManager
The custom index manager implementation does not require the same components as the default
implementations. For example, delegate to a remote indexing service which does not expose a
D i recto ry interface.
Report a bug
23.2.3. Direct oryProvider Configurat ion
578
A D i recto ryP ro vi d er is the Hibernate Search abstraction around a Lucene D i recto ry and
handles the configuration and the initialization of the underlying Lucene resources. D irectory
Providers and their Properties shows the list of the directory providers available in Hibernate Search
together with their corresponding options.
Each indexed entity is associated with a Lucene index (except of the case where multiple entities
share the same index). The name of the index is given by the i nd ex property of the @ Ind exed
annotation. If the i nd ex property is not specified the fully qualified name of the indexed class will be
used as name (recommended).
The D irectoryProvider and any additional options can be configured by using the prefix
hi bernate. search. <indexname>. The name d efaul t (hi bernate. search. d efaul t) is
reserved and can be used to define properties which apply to all indexes. Example 23.2,
Configuring D irectory Providers shows how
hi bernate. search. d efaul t. d i recto ry_pro vi d er is used to set the default directory provider
to be the filesystem one. hi bernate. search. d efaul t. i nd exBase sets then the default base
directory for the indexes. As a result the index for the entity Status is created in
/usr/l ucene/i nd exes/o rg . hi bernate. exampl e. Status.
The index for the R ul e entity, however, is using an in-memory directory, because the default
directory provider for this entity is overridden by the property
hi bernate. search. R ul es. d i recto ry_pro vi d er.
Finally the Acti o n entity uses a custom directory provider C usto mD i recto ryP ro vi d er specified
via hi bernate. search. Acti o ns. d i recto ry_pro vi d er.
Examp le 23.1. Sp ecif yin g t h e In d ex N ame

package org.hibernate.example;
@ Indexed
public class Status { ... }
@ Indexed(index="Rules")
public class Rule { ... }
@ Indexed(index="Actions")
public class Action { ... }
Examp le 23.2. C o n f ig u rin g D irect o ry Pro vid ers

hibernate.search.default.directory_provider = filesystem
hibernate.search.default.indexBase=/usr/lucene/indexes
hibernate.search.Rules.directory_provider = ram
hibernate.search.Actions.directory_provider =
com.acme.hibernate.CustomDirectoryProvider
Note
Using the described configuration scheme you can easily define common rules like the
directory provider and base directory, and override those defaults later on a per index basis.
579
D irect o ry Pro vid ers an d t h eir Pro p ert ies

ram
None
f ilesyst em
File system based directory. The directory used will be <indexBase>/< indexName >
i nd exBase : base directory
i nd exName: override @Indexed.index (useful for sharded indexes)
l o cki ng _strateg y : optional, see Section 23.2.7, LockFactory Configuration
fi l esystem_access_type: allows to determine the exact type of FSD i recto ry
implementation used by this D i recto ryP ro vi d er. Allowed values are auto (the
default value, selects NIO FSD i recto ry on non Windows systems,
Si mpl eFSD i recto ry on Windows), si mpl e (Si mpl eFSD i recto ry), ni o
(NIO FSD i recto ry), mmap (MMapD i recto ry). Refer to Javadocs of these D i recto ry
implementations before changing this setting. Even though NIO FSD i recto ry or
MMapD i recto ry can bring substantial performance boosts they also have their issues.
f ilesyst em- mast er
File system based directory. Like fi l esystem. It also copies the index to a source
directory (aka copy directory) on a regular basis.
The recommended value for the refresh period is (at least) 50% higher that the time to copy
the information (default 3600 seconds - 60 minutes).
Note that the copy is based on an incremental copy mechanism reducing the average copy
time.
D irectoryProvider typically used on the master node in a JMS back end cluster.
The buffer_si ze_o n_co py optimum depends on your operating system and available
RAM; most people reported good results using values between 16 and 64MB.
i nd exBase: base directory
so urceBase: source (copy) base directory.
so urce: source directory suffix (default to @ Ind exed . i nd ex). The actual source
directory name being <so urceBase>/<so urce>
refresh: refresh period in seconds (the copy will take place every refresh seconds). If
a copy is still in progress when the following refresh period elapses, the second copy
operation will be skipped.
buffer_si ze_o n_co py: The amount of MegaBytes to move in a single low level copy
instruction; defaults to 16MB.
580
MMapD i recto ry can bring substantial performance boosts, there are also issues of
which you need to be aware.
f ilesyst em- slave
File system based directory. Like fi l esystem, but retrieves a master version (source) on a
regular basis. To avoid locking and inconsistent search results, 2 local copies are kept.
The recommended value for the refresh period is (at least) 50% higher that the time to copy
the information (default 3600 seconds - 60 minutes).
Note that the copy is based on an incremental copy mechanism reducing the average copy
time. If a copy is still in progress when refresh period elapses, the second copy operation
will be skipped.
D irectoryProvider typically used on slave nodes using a JMS back end.
The buffer_si ze_o n_co py optimum depends on your operating system and available
RAM; most people reported good results using values between 16 and 64MB.
i nd exBase: Base directory
so urceBase: Source (copy) base directory.
so urce: Source directory suffix (default to @ Ind exed . i nd ex). The actual source
directory name being <so urceBase>/<so urce>
refresh: refresh period in second (the copy will take place every refresh seconds).
buffer_si ze_o n_co py: The amount of MegaBytes to move in a single low level copy
instruction; defaults to 16MB.
retry_marker_l o o kup : optional, default to 0. D efines how many times Hibernate
Search checks for the marker files in the source directory before failing. Waiting 5
seconds between each try.
retry_i ni ti al i ze_peri o d : optional, set an integer value in seconds to enable the
retry initialize feature: if the slave can't find the master index it will try again until it's
found in background, without preventing the application to start: fullText queries
performed before the index is initialized are not blocked but will return empty results.
When not enabling the option or explicitly setting it to zero it will fail with an exception
instead of scheduling a retry timer. To prevent the application from starting without an
invalid index but still control an initialization timeout, see retry_marker_l o o kup
instead.
581
MMapD i recto ry can bring substantial performance boosts you need also to be aware
of the issues.
Note
If the built-in directory providers do not fit your needs, you can write your own directory
provider by implementing the o rg . hi bernate. sto re. D i recto ryP ro vi d er interface. In
this case, pass the fully qualified class name of your provider into the d i recto ry_pro vi d er
property. You can pass any additional properties using the prefix
hi bernate. search. <indexname>.
Report a bug
23.2.4 . Sharding Indexes

In some cases it can be useful to split (shard) the indexed data of a given entity into several Lucene
indexes.
Warning
Sharding should only be implemented if the advantages outweigh the disadvantages.
Searching sharded indexes will typically be slower as all shards have to be opened for a
single search.
Possible use cases for sharding are:
A single index is so large that index update times are slowing the application down.
A typical search will only hit a subset of the index, such as when data is naturally segmented by
customer, region or application.
By default sharding is not enabled unless the number of shards is configured. To do this use the
hi bernate. search. <i nd exName>. shard i ng _strateg y. nbr_o f_shard s property.
Examp le 23.3. En ab lin g In d ex Sh ard in g

In this example 5 shards are enabled.
hibernate.search.<indexName>.sharding_strategy.nbr_of_shards = 5
Responsible for splitting the data into sub-indexes is the Ind exShard i ng Strateg y. The default
sharding strategy splits the data according to the hash value of the ID string representation
(generated by the Fi el d Bri d g e). This ensures a fairly balanced sharding. You can replace the
default strategy by implementing a custom Ind exShard i ng Strateg y. To use your custom strategy
you have to set the hi bernate. search. <i nd exName>. shard i ng _strateg y property.
Examp le 23.4 . Sp ecif yin g a C u st o m Sh ard in g St rat eg y
582
hibernate.search.<indexName>.sharding_strategy =
my.shardingstrategy.Implementation
The Ind exShard i ng Strateg y property also allows for optimizing searches by selecting which
shard to run the query against. By activating a filter a sharding strategy can select a subset of the
shards used to answer a query (Ind exShard i ng Strateg y. g etInd exManag ersFo rQ uery) and
thus speed up the query execution.
Each shard has an independent Ind exManag er and so can be configured to use a different
directory provider and back end configuration. The Ind exManag er index names for the Animal
entity in Example 23.5, Sharding Configuration for Entity Animal are Ani mal . 0 to Ani mal . 4 . In
other words, each shard has the name of its owning index followed by . (dot) and its index number.
Examp le 23.5. Sh ard in g C o n f ig u rat io n f o r En t it y An imal

hibernate.search.default.indexBase = /usr/lucene/indexes
hibernate.search.Animal.sharding_strategy.nbr_of_shards = 5
hibernate.search.Animal.directory_provider = filesystem
hibernate.search.Animal.0.indexName = Animal00
hibernate.search.Animal.3.indexBase = /usr/lucene/sharded
hibernate.search.Animal.3.indexName = Animal03
In Example 23.5, Sharding Configuration for Entity Animal , the configuration uses the default id
string hashing strategy and shards the Ani mal index into 5 sub-indexes. All sub-indexes are
filesystem instances and the directory where each sub-index is stored is as followed:
for sub-index 0: /usr/l ucene/i nd exes/Ani mal 0 0 (shared indexBase but overridden
indexName)
for sub-index 1: /usr/l ucene/i nd exes/Ani mal . 1 (shared indexBase, default indexName)
for sub-index 3: /usr/l ucene/shared /Ani mal 0 3 (overridden indexBase, overridden
indexName)
When implementing a Ind exShard i ng Strateg y any field can be used to determine the sharding
selection. Consider that to handle deletions, purg e and purg eAl l operations, the implementation
might need to return one or more indexes without being able to read all the field values or the primary
identifier. In that case the information is not enough to pick a single index, all indexes should be
returned, so that the delete operation will be propagated to all indexes potentially containing the
documents to be deleted.
Report a bug
23.2.5. Worker Configurat ion

It is possible to refine how Hibernate Search interacts with Lucene through the worker configuration.
There exist several architectural components and possible extension points. Let's have a closer look.
First there is a Wo rker. An implementation of the Wo rker interface is responsible for receiving all
entity changes, queuing them by context and applying them once a context ends. The most intuitive
583
context, especially in connection with ORM, is the transaction. For this reason Hibernate Search will
per default use the T ransacti o nal Wo rker to scope all changes per transaction. One can,
however, imagine a scenario where the context depends for example on the number of entity changes
or some other application (lifecycle) events. For this reason the Wo rker implementation is
configurable as shown in Table 23.1, Scope configuration .
T ab le 23.1. Sco p e co n f ig u rat io n
Pro p ert y
hibernate.search.worker.scope
hibernate.search.worker.*
hibernate.search.worker.batch_size
D escrip t io n
The fully qualified class name of the Wo rker
implementation to use. If this property is not set,
empty or transacti o n the default
T ransacti o nal Wo rker is used.
All configuration properties prefixed with
hi bernate. search. wo rker are passed to the
Worker during initialization. This allows adding
custom, worker specific parameters.
D efines the maximum number of indexing
operation batched per context. Once the limit is
reached indexing will be triggered even though
the context has not ended yet. This property
only works if the Wo rker implementation
delegates the queued work to
BatchedQueueingProcessor (which is what the
T ransacti o nal Wo rker does)
Once a context ends it is time to prepare and apply the index changes. This can be done
synchronously or asynchronously from within a new thread. Synchronous updates have the
advantage that the index is at all times in sync with the databases. Asynchronous updates, on the
other hand, can help to minimize the user response time. The drawback is potential discrepancies
between database and index states. Lets look at the configuration options shown in Table 23.2,
Execution configuration .
Note
The following options can be different on each index; in fact they need the indexName prefix or
use d efaul t to set the default value for all indexes.
T ab le 23.2. Execu t io n co n f ig u rat io n

Pro p ert y
hibernate.search.<indexName>.
worker.execution
D escrip t io n
sync: synchronous execution (default)
worker.thread_pool.size
The backend can apply updates from the same

transaction context (or batch) in parallel, using
a threadpool. The default value is 1. You can
experiment with larger values if you have many
operations per transaction.
584
async: asynchronous execution
worker.buffer_queue.max
D efines the maximal number of work queue if the

thread poll is starved. Useful only for
asynchronous execution. D efault to infinite. If
the limit is reached, the work is done by the main
thread.
So far all work is done within the same Virtual Machine (VM), no matter which execution mode. The
total amount of work has not changed for the single VM. Luckily there is a better approach, namely
delegation. It is possible to send the indexing work to a different server by configuring
hibernate.search.default.worker.backend - see Table 23.3, Backend configuration . Again this
option can be configured differently for each index.
T ab le 23.3. B acken d co n f ig u rat io n
Pro p ert y
hibernate.search.<indexName>.worker.backend
D escrip t io n
l ucene: The default backend which runs index
updates in the same VM. Also used when the
property is undefined or empty.
jms: JMS backend. Index updates are send to a
JMS queue to be processed by an indexing
master. See Table 23.4, JMS backend
configuration for additional configuration
options and Section 23.2.5.1, JMS
Master/Slave Back End for a more detailed
description of this setup.
bl ackho l e: Mainly a test/developer setting
which ignores all indexing work
You can also specify the fully qualified name of
a class implementing
Backend Q ueueP ro cesso r. This way you can
implement your own communication layer. The
implementation is responsible for returning a
R unnabl e instance which on execution will
process the index work.
T ab le 23.4 . JMS b acken d co n f ig u rat io n

Pro p ert y
D escrip t io n
hibernate.search.<indexName>.worker.jndi.*
D efines the JND I properties to initiate the

InitialContext (if needed). JND I is only used by
the JMS back end.
Mandatory for the JMS back end. D efines the
JND I name to lookup the JMS connection
factory from (/C o nnecti o nFacto ry by default
in Red Hat JBoss Enterprise Application
Platform)
Mandatory for the JMS back end. D efines the
JND I name to lookup the JMS queue from. The
queue will be used to post work messages.
worker.jms.connection_factory
worker.jms.queue
585
Warning
As you probably noticed, some of the shown properties are correlated which means that not all
combinations of property values make sense. In fact you can end up with a non-functional
configuration. This is especially true for the case that you provide your own implementations
of some of the shown interfaces. Make sure to study the existing code before you write your
own Wo rker or Backend Q ueueP ro cesso r implementation.
Report a bug
2 3.2 .5 .1 . JMS Mast e r/Slave Back End

This section describes in greater detail how to configure the Master/Slave Hibernate Search
architecture.
586
Fig u re 23.3. JMS B acken d C o n f ig u rat io n

Report a bug
2 3.2 .5 .2 . Slave No de s
Every index update operation is sent to a JMS queue. Index querying operations are executed on a
local index copy.
Examp le 23.6 . JMS Slave co n f ig u rat io n

### slave configuration
## DirectoryProvider
# (remote) master location
hibernate.search.default.sourceBase =
/mnt/mastervolume/lucenedirs/mastercopy
# local copy location
hibernate.search.default.indexBase = /Users/prod/lucenedirs
# refresh every half hour
hibernate.search.default.refresh = 1800
# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-slave
## Backend configuration
hibernate.search.default.worker.backend = jms
hibernate.search.default.worker.jms.connection_factory =
/ConnectionFactory
hibernate.search.default.worker.jms.queue = queue/hibernatesearch
#optional jndi configuration (check your JMS provider for more
information)
## Optional asynchronous execution strategy
# hibernate.search.default.worker.execution = async
# hibernate.search.default.worker.thread_pool.size = 2
# hibernate.search.default.worker.buffer_queue.max = 50
Note
A file system local copy is recommended for faster search results.
Report a bug
2 3.2 .5 .3. Mast e r No de

Every index update operation is taken from a JMS queue and executed. The master index is copied
on a regular basis.
587
Examp le 23.7. JMS Mast er co n f ig u rat io n

### master configuration
## DirectoryProvider
# (remote) master location where information is copied to
hibernate.search.default.sourceBase =
/mnt/mastervolume/lucenedirs/mastercopy
# local master location
hibernate.search.default.indexBase = /Users/prod/lucenedirs
# refresh every half hour
hibernate.search.default.refresh = 1800
# appropriate directory provider
hibernate.search.default.directory_provider = filesystem-master
## Backend configuration
#Backend is the default lucene one
In addition to the Hibernate Search framework configuration, a Message D riven Bean has to be
written and set up to process the index works queue through JMS.
Examp le 23.8. Messag e D riven B ean p ro cessin g t h e in d exin g q u eu e

@ MessageDriven(activationConfig = {
@ ActivationConfigProperty(propertyName="destinationType",
propertyValue="javax.jms.Queue"),
@ ActivationConfigProperty(propertyName="destination",
propertyValue="queue/hibernatesearch"),
@ ActivationConfigProperty(propertyName="DLQMaxResent",
propertyValue="1")
} )
public class MDBSearchController extends
AbstractJMSHibernateSearchController
implements MessageListener {
@ PersistenceContext EntityManager em;
//method retrieving the appropriate session
protected Session getSession() {
return (Session) em.getDelegate();
}
//potentially close the session opened in #getSession(), not
needed here
protected void cleanSessionIfNeeded(Session session)
}
}
This example inherits from the abstract JMS controller class available in the Hibernate Search source
code and implements a JavaEE MD B. This implementation is given as an example and can be
588
adjusted to make use of non Java EE Message D riven Beans. For more information about the
g etSessi o n() and cl eanSessi o nIfNeed ed (), see
AbstractJMSHi bernateSearchC o ntro l l er's javadoc.
Report a bug
23.2.6. T uning Lucene Indexing

2 3.2 .6 .1 . T uning Luce ne Inde xing Pe rfo rm ance
Hibernate Search is used to tune the Lucene indexing performance by specifying a set of parameters
which are passed through to underlying Lucene Ind exWri ter such as merg eFacto r,
maxMerg eD o cs, and maxBuffered D o cs. Specify these parameters either as default values
applying for all indexes, on a per index basis, or even per shard.
There are several low level Ind exWri ter settings which can be tuned for different use cases. These
parameters are grouped by the i nd exwri ter keyword:
hibernate.search.[default|<indexname>].indexwriter.<parameter_name>
If no value is set for an i nd exwri ter value in a specific shard configuration, Hibernate Search
checks the index section, then at the default section.
The configuration in the following table will result in these settings applied on the second shard of
the Ani mal index:
max_merg e_d o cs = 10
merg e_facto r = 20
ram_buffer_si ze = 64MB
term_i nd ex_i nterval = Lucene default
All other values will use the defaults defined in Lucene.
The default for all values is to leave them at Lucene's own default. The values listed in Table 23.5,
List of indexing performance and behavior properties depend for this reason on the version of
Lucene you are using. The values shown are relative to version 2. 4 . For more information about
Lucene indexing performance, see the Lucene documentation.
Note
Previous versions of Hibernate Search had the notion of batch and transacti o n properties.
This is no longer the case as the backend will always perform work using the same settings.
T ab le 23.5. List o f in d exin g p erf o rman ce an d b eh avio r p ro p ert ies

Pro p ert y
D escrip t io n
D ef au lt Valu e
589
Pro p ert y
D escrip t io n
D ef au lt Valu e
hibernate.search.[default|
<indexname>].exclusive_index_use
Set to true when no other process will

need to write to the same index. This
enables Hibernate Search to work in
exclusive mode on the index and
improve performance when writing
changes to the index.
Each index has a separate " pipeline"
which contains the updates to be
applied to the index. When this queue
is full adding more operations to the
queue becomes a blocking operation.
Configuring this setting doesn't make
much sense unless the
wo rker. executi o n is configured as
async.
D etermines the minimal number of
delete terms required before the
buffered in-memory delete terms are
applied and flushed. If there are
documents buffered in memory at the
time, they are merged and a new
segment is created.
Controls the amount of documents
buffered in memory during indexing.
The bigger the more RAM is
consumed.
D efines the largest number of
documents allowed in a segment.
Smaller values perform better on
frequently changing indexes, larger
values provide better search
performance if the index does not
change often.
Controls segment merge frequency
and size.
true (improved
performance,
releases locks
only at shutdown)
<indexname>].max_queue_length
<indexname>].
indexwriter.max_buffered_delete_term
s
<indexname>].
indexwriter.max_buffered_docs
<indexname>].
indexwriter.max_merge_docs
<indexname>].
indexwriter.merge_factor
590
D etermines how often segment

indexes are merged when insertion
occurs. With smaller values, less RAM
is used while indexing, and searches
on unoptimized indexes are faster, but
indexing speed is slower. With larger
values, more RAM is used during
indexing, and while searches on
unoptimized indexes are slower,
indexing is faster. Thus larger values
(> 10) are best for batch index
creation, and smaller values (< 10) for
indexes that are interactively
maintained. The value must not be
lower than 2.
10 0 0
D isabled (flushes
by RAM usage)
D isabled (flushes
by RAM usage)
Unlimited
(Integer.MAX_VAL
UE)
10
Pro p ert y
D escrip t io n
D ef au lt Valu e
<indexname>].
indexwriter.merge_min_size

and size.
0 MB (actually
~1K)
Segments smaller than this size (in

MB) are always considered for the
next segment merge operation.
Setting this too large might result in
expensive merge operations, even
tough they are less frequent.
See also
o rg . apache. l ucene. i nd ex. Lo g
D o cMerg eP o l i cy. mi nMerg eSi ze.
<indexname>].
indexwriter.merge_max_size

and size.
Unlimited
Segments larger than this size (in MB)

are never merged in bigger segments.
This helps reduce memory
requirements and avoids some
merging operations at the cost of
optimal search speed. When
optimizing an index this value is
ignored.
See also
D o cMerg eP o l i cy. maxMerg eSi ze.
<indexname>].
indexwriter.merge_max_optimize_size

and size.
Unlimited

are not merged in bigger segments
even when optimizing the index (see
merg e_max_si ze setting as well).
Applied to
D o cMerg eP o l i cy.
maxMerg eSi zeFo rO pti mi ze.
591
Pro p ert y
D escrip t io n
<indexname>].
and size.
indexwriter.merge_calibrate_by_delete
Set to fal se to not consider deleted
s
documents when estimating the merge
policy.
D ef au lt Valu e
true
Applied to
Merg eP o l i cy.
cal i brateSi zeByD el etes.
<indexname>].
indexwriter.ram_buffer_size
Controls the amount of RAM in MB

dedicated to document buffers. When
used together max_buffered_docs a
flush occurs for whichever event
happens first.
16 MB
Generally for faster indexing

performance it's best to flush by RAM
usage instead of document count and
use as large a RAM buffer as you can.
<indexname>].
indexwriter.term_index_interval
Expert: Set the interval between

indexed terms.
<indexname>].
indexwriter.use_compound_file
The advantage of using the

compound file format is that less file
descriptors are used. The
disadvantage is that indexing takes
more time and temporary disk space.
You can set this parameter to fal se
in an attempt to improve the indexing
time, but you could run out of file
descriptors if merg eFacto r is also
large.
Large values cause less memory to be

used by IndexReader, but slow
random-access to terms. Small values
cause more memory to be used by an
IndexReader, and speed randomaccess to terms. See Lucene
documentation for more details.
Boolean parameter, use " true" or

" fal se" . The default value for this
option is true.
592
128
true
Pro p ert y
D escrip t io n
D ef au lt Valu e
hibernate.search.enable_dirty_check
Not all entity changes require a

Lucene index update. If all of the
updated entity properties (dirty
properties) are not indexed, Hibernate
Search skips the re-indexing process.
true
D isable this option if you use custom

Fi el d Bri d g es which need to be
invoked at each update event (even
though the property for which the field
bridge is configured has not
changed).
This optimization will not be applied
on classes using a @ C l assBri d g e
or a @ D ynami cBo o st.
option is true.
Warning
The bl ackho l e backend is not meant to be used in production, only as a tool to identify
indexing bottlenecks.
Report a bug
2 3.2 .6 .2 . T he Luce ne Inde xWrit e r

There are several low level Ind exWri ter settings which can be tuned for different use cases. These
parameters are grouped by the i nd exwri ter keyword:
default.<indexname>.indexwriter.<parameter_name>
If no value is set for i nd exwri ter in a shard configuration, Hibernate Search looks at the index
section and then at the default section.
Report a bug
2 3.2 .6 .3. Pe rfo rm ance Opt io n Co nfigurat io n

The following configuration will result in these settings being applied on the second shard of the
Ani mal index:
Examp le 23.9 . Examp le p erf o rman ce o p t io n co n f ig u rat io n

default.Animals.2.indexwriter.max_merge_docs = 10
default.Animals.2.indexwriter.merge_factor = 20
default.Animals.2.indexwriter.term_index_interval = default
593
default.indexwriter.max_merge_docs = 100
default.indexwriter.ram_buffer_size = 64
max_merg e_d o cs = 10
merg e_facto r = 20
ram_buffer_si ze = 64MB
term_i nd ex_i nterval = Lucene default
All other values will use the defaults defined in Lucene.
The Lucene default values are the default setting for Hibernate Search. Therefore, the values listed in
the following table depend on the version of Lucene being used. The values shown are relative to
version 2. 4 . For more information about Lucene indexing performance, see the Lucene
documentation.
Note
The back end will always perform work using the same settings.
T ab le 23.6 . List o f in d exin g p erf o rman ce an d b eh avio r p ro p ert ies

Pro p ert y
D escrip t io n
D ef au lt Valu e
default.
<indexname>.exclusive_index_use
Set to true when no other process will

need to write to the same index. This
enables Hibernate Search to work in
exclusive mode on the index and
improve performance when writing
changes to the index.
Each index has a separate " pipeline"
which contains the updates to be
applied to the index. When this queue
is full adding more operations to the
queue becomes a blocking operation.
Configuring this setting doesn't make
much sense unless the
wo rker. executi o n is configured as
async.
D etermines the minimal number of
delete terms required before the
buffered in-memory delete terms are
applied and flushed. If there are
documents buffered in memory at the
time, they are merged and a new
segment is created.
Controls the amount of documents
buffered in memory during indexing.
The bigger the more RAM is
consumed.
true (improved
performance,
releases locks
only at shutdown)
default.
<indexname>.max_queue_length
default.
<indexname>.indexwriter.max_buffere
d_delete_terms
default.
<indexname>.indexwriter.max_buffere
d_docs
594
10 0 0
D isabled (flushes
by RAM usage)
D isabled (flushes
by RAM usage)
Pro p ert y
D escrip t io n
D ef au lt Valu e
default.
D efines the largest number of
<indexname>.indexwriter.max_merge_ documents allowed in a segment.
docs
Smaller values perform better on
frequently changing indexes, larger
values provide better search
performance if the index does not
change often.
default.
<indexname>.indexwriter.merge_facto and size.
r
D etermines how often segment
indexes are merged when insertion
occurs. With smaller values, less RAM
is used while indexing, and searches
on unoptimized indexes are faster, but
indexing speed is slower. With larger
values, more RAM is used during
indexing, and while searches on
unoptimized indexes are slower,
indexing is faster. Thus larger values
(> 10) are best for batch index
creation, and smaller values (< 10) for
indexes that are interactively
maintained. The value must not be
lower than 2.
Unlimited
(Integer.MAX_VAL
UE)
default.
<indexname>.indexwriter.merge_min_
size
0 MB (actually
~1K)

and size.
10
Segments smaller than this size (in

MB) are always considered for the
next segment merge operation.
Setting this too large might result in
expensive merge operations, even
tough they are less frequent.
See also
D o cMerg eP o l i cy. mi nMerg eSi ze.
595
Pro p ert y
D escrip t io n
default.
<indexname>.indexwriter.merge_max_ and size.
size
are never merged in bigger segments.
D ef au lt Valu e
Unlimited
This helps reduce memory

requirements and avoids some
merging operations at the cost of
optimal search speed. When
optimizing an index this value is
ignored.
See also
D o cMerg eP o l i cy. maxMerg eSi ze.
default.
<indexname>.indexwriter.merge_max_ and size.
optimize_size
are not merged in bigger segments
even when optimizing the index (see
merg e_max_si ze setting as well).
Unlimited
Applied to
D o cMerg eP o l i cy.
maxMerg eSi zeFo rO pti mi ze.
default.
<indexname>.indexwriter.merge_calib
rate_by_deletes

and size.
true
Set to fal se to not consider deleted

documents when estimating the merge
policy.
Applied to
Merg eP o l i cy.
cal i brateSi zeByD el etes.
default.
<indexname>.indexwriter.ram_buffer_
size
Controls the amount of RAM in MB

dedicated to document buffers. When
used together max_buffered_docs a
flush occurs for whichever event
happens first.
Generally for faster indexing
performance it's best to flush by RAM
usage instead of document count and
use as large a RAM buffer as you can.
596
16 MB
Pro p ert y
D escrip t io n
D ef au lt Valu e
default.
Expert: Set the interval between
<indexname>.indexwriter.term_index_i indexed terms.
nterval
Large values cause less memory to be
used by IndexReader, but slow
random-access to terms. Small values
cause more memory to be used by an
IndexReader, and speed randomaccess to terms. See Lucene
documentation for more details.
128
default.
<indexname>.indexwriter.use_compo
und_file
true
The advantage of using the

compound file format is that less file
descriptors are used. The
disadvantage is that indexing takes
more time and temporary disk space.
You can set this parameter to fal se
in an attempt to improve the indexing
time, but you could run out of file
descriptors if merg eFacto r is also
large.
option is true.
default.enable_dirty_check
Not all entity changes require a

Lucene index update. If all of the
updated entity properties (dirty
properties) are not indexed, Hibernate
Search skips the re-indexing process.
true
D isable this option if you use custom

Fi el d Bri d g es which need to be
invoked at each update event (even
though the property for which the field
bridge is configured has not
changed).
This optimization will not be applied
on classes using a @ C l assBri d g e
or a @ D ynami cBo o st.
option is true.
Report a bug
2 3.2 .6 .4 . T uning t he Inde xing Spe e d

When the architecture permits it, keep d efaul t. excl usi ve_i nd ex_use= true for improved index
writing efficiency.
When tuning indexing speed the recommended approach is to focus first on optimizing the object
597
loading, and then use the timings you achieve as a baseline to tune the indexing process. Set the
bl ackho l e as worker back end and start your indexing routines. This back end does not disable
Hibernate Search: it generates the required change sets to the index, but discards them instead of
flushing them to the index. In contrast to setting the hi bernate. search. i nd exi ng _strateg y to
manual , using bl ackho l e will possibly load more data from the database because associated
entities are re-indexed as well.
hibernate.search.[default|<indexname>].worker.backend blackhole
Warning
The bl ackho l e back end is not to be used in production, only as a diagnostic tool to identify
indexing bottlenecks.
Report a bug
2 3.2 .6 .5 . Co nt ro l Se gm e nt Size
The following options configure the maximum size of segments created:
merge_max_size
merge_max_optimize_size
merge_calibrate_by_deletes
Examp le 23.10. C o n t ro l Seg men t Siz e

//to be fairly confident no files grow above 15MB, use:
hibernate.search.default.indexwriter.ram_buffer_size = 10
hibernate.search.default.indexwriter.merge_max_optimize_size = 7
hibernate.search.default.indexwriter.merge_max_size = 7
Set the max_size for merge operations to less than half of the hard limit segment size, as merging
segments combines two segments into one larger segment.
A new segment may initially be a larger size than expected, however a segment is never created
significantly larger than the ram_buffer_size. This threshold is checked as an estimate.
Report a bug
23.2.7. LockFact ory Configurat ion

The Lucene D irectory can be configured with a custom locking strategy via Lo cki ng Facto ry for
each index managed by Hibernate Search.
Some locking strategies require a filesystem level lock, and may be used on RAM-based indexes.
When using this strategy the Ind exBase configuration option must be specified to point to a
filesystem location in which to store the lock marker files.
To select a locking factory, set the hi bernate. search. <i nd ex>. l o cki ng _strateg y option to
one the following options:
598
simple
native
single
none
T ab le 23.7. List o f availab le Lo ckFact o ry imp lemen t at io n s
n ame
C lass
D escrip t io n
simple
org.apache.lucen Safe implementation based on Java's File API, it marks the

e.store.
usage of the index by creating a marker file.
SimpleFSLockFac
If for some reason you had to kill your application, you will
tory
need to remove this file before restarting it.
native
org.apache.lucen
e.store.
NativeFSLockFact
ory
As does si mpl e this also marks the usage of the index by

creating a marker file, but this one is using native OS file
locks so that even if the JVM is terminated the locks will be
cleaned up.
This implementation has known problems on NFS, avoid it
on network shares.
nati ve is the default implementation for the fi l esystem,
fi l esystem-master and fi l esystem-sl ave directory
providers.
single
org.apache.lucen
e.store.
SingleInstanceLo
ckFactory
This LockFactory doesn't use a file marker but is a Java

object lock held in memory; therefore it's possible to use it
only when you are sure the index is not going to be
shared by any other process.
This is the default implementation for the ram directory
provider.
none
org.apache.lucen
e.store.
NoLockFactory
Changes to this index are not coordinated by a lock.
The following is an example of locking strategy configuration:

hibernate.search.default.locking_strategy = simple
hibernate.search.Animals.locking_strategy = native
hibernate.search.Books.locking_strategy =
org.custom.components.MyLockingFactory
Report a bug
23.2.8. Except ion Handling Configurat ion

Hibernate Search allows you to configure how exceptions are handled during the indexing process.
If no configuration is provided then exceptions are logged to the log output by default. It is possible
to explicitly declare the exception logging mechanism as follows:
599
hibernate.search.error_handler = log
The default exception handling occurs for both synchronous and asynchronous indexing. Hibernate
Search provides an easy mechanism to override the default error handling implementation.
In order to provide your own implementation you must implement the Erro rHand l er interface, which
provides the hand l e(Erro rC o ntext co ntext) method. Erro rC o ntext provides a reference to
the primary LuceneWo rk instance, the underlying exception and any subsequent LuceneWo rk
instances that could not be processed due to the primary exception.
public interface ErrorContext {
List<LuceneWork> getFailingOperations();
LuceneWork getOperationAtFault();
Throwable getThrowable();
boolean hasErrors();
}
To register this error handler with Hibernate Search you must declare the fully qualified classname of
your Erro rHand l er implementation in the configuration properties:
hibernate.search.error_handler = CustomerErrorHandler
Report a bug
23.2.9. Index Format Compat ibilit y

Hibernate Search does not currently offer a backwards compatible API or tool to facilitate porting
applications to newer versions. The API uses Apache Lucene for index writing and searching.
Occasionally an update to the index format may be required. In this case, there is a possibility that
data will need to be re-indexed if Lucene is unable to read the old format.
Warning
Back up indexes before attempting to update the index format.
Hibernate Search exposes the hi bernate. search. l ucene_versi o n configuration property. This
property instructs Analyzers and other Lucene classes to conform to their behaviour as defined in an
older version of Lucene. See also o rg . apache. l ucene. uti l . Versi o n contained in the
l ucene-co re. jar. If the option is not specified, Hibernate Search instructs Lucene to use the
version default. It is recommended that the version used is explicitly defined in the configuration to
prevent automatic changes when an upgrade occurs. After an upgrade, the configuration values can
be updated explicitly if required.
Examp le 23.11. Fo rce An alyz ers t o b e co mp at ib le wit h a Lu cen e 3.0 creat ed in d ex

hibernate.search.lucene_version = LUCENE_30
The configured SearchFacto ry is global and affects all Lucene APIs that contain the relevant
parameter. If Lucene is used and Hibernate Search is bypassed, apply the same value to it for
consistent results.
600
Report a bug
23.2.10. Disable Hibernat e Search

Hibernate Search can be partially or completely disabled as required. Hibernate Search's indexing
can be disabled, for example, if the index is read-only, or you prefer to perform indexing manually,
rather than automatically. It is also possible to completely disable Hibernate Search, preventing
indexing and searching.
D isab le In d exin g
To disable Hibernate Search indexing, change the i nd exi ng _strateg y configuration option to
manual , then restart JBoss EAP.
hibernate.search.indexing_strategy = manual
D isab le H ib ern at e Search C o mp let ely
To disable Hibernate Search completely, disable all listeners by changing the
auto reg i ster_l i steners configuration option to fal se, then restart JBoss EAP.
hibernate.search.autoregister_listeners = false
Report a bug
23.3. Monit oring

23.3.1. Monit oring
Hibernate Search offers access to a Stati sti cs object via SearchFacto ry. g etStati sti cs(). It
allows you, for example, to determine which classes are indexed and how many entities are in the
index. This information is always available. However, by specifying the
hi bernate. search. g enerate_stati sti cs property in your configuration you can also collect
total and average Lucene query and object loading timings.
Hibernate Search provides several methods of monitoring its operations. The list of indexed classes
and number of entities per index are always available from the Stati sti cs object via the
SearchFacto ry. g etStati sti cs() method. To obtain total and average Lucene query and object
loading timings, specify the hi bernate. search. g enerate_stati sti cs property in your
configuration.
Access t o St at ist ics via JMX
To enable access to statistics via JMX, set the property hi bernate. search. jmx_enabl ed to
true. This will automatically register the Stati sti csInfo MBean bean, providing access to
statistics via the Stati sti cs object. D epending on your configuration the
Ind exi ng P ro g ressMo ni to rMBean bean may also be registered.
Mo n it o rin g In d exin g
If the mass indexer API is used, you can monitor indexing progress via the
Ind exi ng P ro g ressMo ni to rMBean bean. The bean is only bound to JMX while indexing is in
progress.
601
Note
JMX beans can be accessed remotely via JConsole by setting the system property
co m. sun. manag ement. jmxremo te to true.
Report a bug
602
Chapter 24. Deploy JBoss EAP 6 on Amazon EC2

24 .1. Int roduct ion
24 .1.1. About Amaz on EC2
Amazon Elastic Compute Cloud (Amazon EC2) is a service operated by amazon.com that provides
customers with a customizable virtual computing environment. An Amazon Machine Image (AMI) can
be booted using the service to create a virtual machine or instance. Users can install whatever
software they require on an instance and are charged according to the capacity used. Amazon EC2
is designed to be flexible and allow users to quickly scale their deployed applications.
You can read more about it at the Amazon EC2 website, http://aws.amazon.com/ec2/.
Report a bug
24 .1.2. About Amaz on Machine Inst ances (AMIs)

An Amazon Machine Image (AMI) is a template for a EC2 virtual machine instance. Users create EC2
instances by selecting an appropriate AMI to create the instance from. The primary component of an
AMI is a read-only filesystem that contains an installed operating system as well as other software.
Each AMI has different software installed for different use cases. Amazon EC2 includes many AMIs to
choose from provided by both amazon.com and third parties. Users can also create their own custom
AMIs.
Report a bug
24 .1.3. About JBoss Cloud Access

JBoss Cloud Access is a Red Hat subscription feature that provides support for JBoss EAP 6 on Red
Hat certified cloud infrastructure providers such as Amazon EC2. JBoss Cloud Access allows you to
move your subscriptions between traditional servers and public cloud-based resources in a simple
and cost-effective manner.
You can find out more details about it at http://www.redhat.com/en/technologies/cloudcomputing/cloud-access.
Report a bug
24 .1.4 . JBoss Cloud Access Feat ures

Membership in the JBoss Cloud Access program provides access to supported private Amazon
Machine Images (AMIs) created by Red Hat.
The Red Hat AMIs have the following software pre-installed and fully supported by Red hat:
Red Hat Enterprise Linux 6
JBoss EAP 6
The JBoss Operations Network (JON) 3 agent
Product updates with RPMs using Red Hat Update Infrastructure.
603
Each of the Red Hat AMIs are only a starting point, requiring further configuration to the requirements
of your application.
Important
JBoss Cloud Access does not currently provide support for the full-ha profile, in either
standalone instances or a managed domain.
Report a bug
24 .1.5. Support ed Amaz on EC2 Inst ance T ypes

JBoss Cloud Access supports the following Amazon EC2 instance types. Refer to the Amazon EC2
User Guide for more details about each instance type,
http://docs.amazonwebservices.com/AWSEC2/latest/UserGuide/instance-types.html.
T ab le 24 .1. Su p p o rt ed Amaz o n EC 2 In st an ce T yp es
In st an ce T yp e
D escrip t io n
Standard Instance
Standard Instances are general purpose environments with a balanced

memory-to-CPU ratio.
High Memory Instances have more memory allocated to them than
Standard Instances. High Memory Instances are suited for high
throughput applications such as databases or memory caching
applications.
High CPU Instances have more CPU resources allocated than memory
and are suited for relatively low throughput but CPU intensive
applications.
High Memory Instance
High CPU Instance
Important
The instance type Mi cro (t1. mi cro ) is not suitable for deployment of JBoss EAP 6.
Report a bug
24 .1.6. Support ed Red Hat AMIs

The supported Red Hat AMIs can be identified by their AMI Name.
The JBoss EAP 6 AMIs are named using the following syntax:
RHEL-osversion-JBEAP-version-arch-creationdate
version is the version number of JBoss EAP installed in the AMI. Example 6 . 3.
osversion is the version number of Red Hat Enterprise Linux installed in the AMI. Example 6 . 2.
arch is the architecture of the AMI. This will be x86 _6 4 or i 386 .
creationdate is the date that the AMI was created in the format of YYYYMMDD. Example 20 120 50 1.
604
Chapt er 2 4 . Deploy JBoss EAP 6 on Amaz on EC2
Example AMI name: R HEL-6 . 2-JBEAP -6 . 0 . 0 -x86 _6 4 -20 120 50 1.

Report a bug
24 .2. Deploying JBoss EAP 6 on Amaz on EC2

24 .2.1. Overview of Deploying JBoss EAP 6 on Amaz on EC2
JBoss EAP 6 can be deployed using the Amazon EC2 AMI. The AMI contains everything that is
required for deployment of clustered and non-clustered instances.
D eploying a non-clustered instance is the easiest scenario. It requires only that you make a few
configuration changes to specify your application deployment when creating the instance.
D eploying clustered instances requires more configuration. It is recommended you create a Virtual
Private Cloud to contain your cluster. Use of a JBoss EAP instance to act as a mod_cluster proxy is
optional but if you take this option, an S3 bucket for the S3_PING JGroups discovery protocol is
also required.
Each of these steps is detailed below but it is assumed that you have some experience with JBoss
EAP 6, Red Hat Enterprise Linux 6 and Amazon EC2.
The following documentation is recommended additional reference:
JBoss EAP 6
https://access.redhat.com/documentation/en-US/JBoss_Enterprise_Application_Platform/
Red Hat Enterprise Linux 6
https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/
Amazon Web Services
http://aws.amazon.com/documentation/
Report a bug
24 .3. Non-clust ered JBoss EAP 6

24 .3.1. About Non-clust ered Inst ances
A non-clustered instance is a single Amazon EC2 instance running JBoss EAP 6. It is not part of a
cluster.
Report a bug
24 .4 . Non-clust ered Inst ances

24 .4 .1. Launch a Non-clust ered JBoss EAP 6 Inst ance
Su mmary
This topic covers the steps required to launch a non-clustered instance of JBoss EAP 6 on a Red Hat
AMI (Amazon Machine Image).
605
Prereq u isit es
A suitable Red Hat AMI. Refer to Section 24.1.6, Supported Red Hat AMIs .
A pre-configured Security Group which allows incoming requests on at least ports 22, 8080, and
9990.
Pro ced u re 24 .1. Lau n ch a N o n - clu st ered In st an ce o f JB o ss EAP 6 o n a R ed H at AMI
( Amaz o n Mach in e Imag e)
1. Configure the User D ata field. The configurable parameters are available here:
Section 24.10.1, Permanent Configuration Parameters , Section 24.10.2, Custom Script
Parameters .
Examp le 24 .1. Examp le U ser D at a Field

The example shows the User D ata field for a non-clustered JBoss EAP 6 instance. The
password for the user ad mi n has been set to ad mi npwd .
JBOSSAS_ADMIN_PASSWORD=adminpwd
JBOSS_IP=0.0.0.0 #listen on all IPs and interfaces
# In production, access to these ports needs to be restricted for
security reasons
PORTS_ALLOWED="9990 9443"
cat> $USER_SCRIPT << "EOF"
# Get the application to be deployed from an Internet URL
# mkdir -p /usr/share/java/jboss-ec2-eap-applications
# wget https://<your secure storage hostname>/<path>/<app
name>.war -O /usr/share/java/jboss-ec2-eap-applications/<app
name>.war
# Create a file of CLI commands to be executed after starting the
server
cat> $USER_CLI_COMMANDS << "EOC"
# deploy /usr/share/java/jboss-ec2-eap-applications/<app
name>.war
EOC
EOF
2. Fo r Pro d u ct io n In st an ces
For a production instance, add the following line beneath the USER _SC R IP T line of the User
D ata field, to ensure security updates are applied on boot.
yum -y update
606
Note
yum -y upd ate should be run regularly, to apply security fixes and enhancements.
3. Launch the Red Hat AMI instance.
R esu lt
A non-clustered instance of JBoss EAP 6 has been configured, and launched on a Red Hat AMI.
Report a bug
24 .4 .2. Deploy an Applicat ion on a non-clust ered JBoss EAP 6 Inst ance
Su mmary
This topic covers deploying an application to a non-clustered JBoss EAP 6 instance on a Red Hat
AMI.
1. A. D ep lo y t h e Samp le Ap p licat io n
Add the following lines to the User D ata field:
# Deploy the sample application from the local filesystem
deploy --force /usr/share/java/jboss-ec2-eap-samples/hello.war
Examp le 24 .2. Examp le U ser D at a Field wit h Samp le Ap p licat io n

This example uses the sample application provided on the Red Hat AMI. It also includes
basic configuration for a non-clustered JBoss EAP 6 instance. The password for the
user ad mi n has been set to ad mi npwd .
# In production, access to these ports needs to be restricted
for security reasons
# Create a file of CLI commands to be executed after starting
the server
deploy --force /usr/share/java/jboss-ec2-eap-samples/hello.war
EOC
EOF
607
B. D ep lo y a C u st o m Ap p licat io n
Add the following lines to the User D ata field, configuring the application name and the
URL:
mkdir -p /usr/share/java/jboss-ec2-eap-applications
wget https://<your secure storage hostname>/<path>/<app
name>.war
Examp le 24 .3. Examp le U ser D at a Field wit h C u st o m Ap p licat io n

This example uses an application called MyApp, and includes basic configuration for a
non-clustered JBoss EAP 6 instance. The password for the user ad mi n has been set to
ad mi npwd .
# In production, access to these ports needs to be restricted
for security reasons
mkdir -p /usr/share/java/jboss-ec2-eap-applications
wget https://PATH_TO_MYAPP/MyApp.war -O /usr/share/java/jbossec2-eap-applications/MyApp.war
# Create a file of CLI commands to be executed after starting
the server
deploy /usr/share/java/jboss-ec2-eap-applications/MyApp.war
EOC
EOF

R esu lt
The application has been successfully deployed to JBoss EAP 6.
Report a bug
24 .4 .3. T est t he Non-clust ered JBoss EAP 6 Inst ance

Su mmary
This topic covers the steps required to test that the non-clustered JBoss EAP 6 is running correctly.
Pro ced u re 24 .2. T est t h e N o n - clu st ered JB o ss EAP 6 In st an ce is R u n n in g C o rrect ly
608
1. D etermine the instance's P ubl i c D NS, located in the instance's details pane.
2. Navigate to http: //<public-DNS>: 80 80 .
3. Confirm that the JBoss EAP home page appears, including a link to the Admin console. If the
home page is not available, refer here: Section 24.11.1, About Troubleshooting Amazon
EC2 .
4. Click on the Ad mi n C o nso l e hyperlink.
5. Log in:
Username: ad mi n
Password: Specified in the User D ata field here: Section 24.4.1, Launch a Non-clustered
JBoss EAP 6 Instance .
6. T est t h e Samp le Ap p licat io n
Navigate to http: //<public-DNS>: 80 80 /hel l o to test that the sample application is
running successfully. The text Hel l o Wo rl d ! should appear in the browser. If the text is
not visible, refer here: Section 24.11.1, About Troubleshooting Amazon EC2 .
7. Log out of the JBoss EAP 6 Admin Console.
R esu lt
The JBoss EAP 6 instance is running correctly.
Report a bug
24 .5. Non-clust ered Managed Domains

24 .5.1. Launch an Inst ance t o Serve as a Domain Cont roller
Su mmary
This topic covers the steps required to launch a non-clustered JBoss EAP 6 managed domain on a
Red Hat AMI (Amazon Machine Image).
Prereq u isit es
Section 24.6.3, Create a Virtual Private Cloud (VPC)
Section 24.6.4, Launch an Apache HTTP Server Instance to Serve as a mod_cluster Proxy and a
NAT Instance for the VPC
Section 24.6.5, Configure the VPC Private Subnet D efault Route
Section 24.6.7, Configure IAM Setup
Section 24.6.9, Configure S3 Bucket Setup
Pro ced u re 24 .3. Lau n ch a n o n - clu st ered JB o ss EAP 6 man ag ed d o main o n a R ed H at
AMI
609
1. In the Security Group tab, ensure all traffic is allowed. Red Hat Enterprise Linux's built-in
firewall capabilities can be used to restrict access if desired.
2. Set the public subnet of the VPC to running.
3. Select a static IP.
4. Configure the User D ata field. The configurable parameters are available here:
Section 24.10.1, Permanent Configuration Parameters , Section 24.10.2, Custom Script
Parameters . For further information on domain controller discovery on Amazon EC2, see
Section 24.5.4, Configuring D omain Controller D iscovery and Failover on Amazon EC2 .
Examp le 24 .4 . Examp le U ser D at a Field

The example shows the User D ata field for a non-clustered JBoss EAP 6 managed domain.
The password for the user ad mi n has been set to ad mi n.
## password that will be used by slave host controllers to
connect to the domain controller
JBOSSAS_ADMIN_PASSWORD=admin
## subnet prefix this machine is connected to
SUBNET=10.0.0.
## S3 domain controller discovery setup
# JBOSS_DOMAIN_S3_SECRET_ACCESS_KEY=<your secret key>
# JBOSS_DOMAIN_S3_ACCESS_KEY=<your access key>
# JBOSS_DOMAIN_S3_BUCKET=<your bucket name>
#### to run the example no modifications below should be needed
####
JBOSS_DOMAIN_CONTROLLER=true
PORTS_ALLOWED="9999 9990 9443"
JBOSS_IP=`hostname | sed -e 's/ip-//' -e 'y/-/./'` #listen on
public/private EC2 IP address
cat > $USER_SCRIPT << "EOF"
## Get the application to be deployed from an Internet URL
name>.war
## Create a file of CLI commands to be executed after starting
the server
# Add the modcluster subsystem to the default profile to set up a
proxy
/profile=default/subsystem=web/connector=ajp:add(name=ajp,protoco
l=AJP/1.3,scheme=http,socket-binding=ajp)
/:composite(steps=[ {"operation" => "add", "address" => [
("profile" => "default"), ("subsystem" => "modcluster") ] },{
"operation" => "add", "address" => [ ("profile" => "default"),
("subsystem" => "modcluster"), ("mod-cluster-config" =>
"configuration") ], "advertise" => "false", "proxy-list" =>
610
"${jboss.modcluster.proxyList}", "connector" => "ajp"}, {

"operation" => "add", "address" => [ ("profile" => "default"),
("subsystem" => "modcluster"), ("mod-cluster-config" =>
"configuration"), ("dynamic-load-provider" => "configuration")
]}, { "operation" => "add", "address" => [ ("profile" =>
"default"), ("subsystem" => "modcluster"), ("mod-cluster-config"
=> "configuration"), ("dynamic-load-provider" =>
"configuration"), ("load-metric" => "busyness")], "type" =>
"busyness"} ])
deploy /usr/share/java/jboss-ec2-eap-samples/hello.war --servergroups=main-server-group
EOC
## this will workaround the problem that in a VPC, instance
hostnames are not resolvable
echo -e "127.0.0.1\tlocalhost.localdomain localhost" > /etc/hosts
echo -e "::1\tlocalhost6.localdomain6 localhost6" >> /etc/hosts
for (( i=1 ; i<255 ; i++ )); do
echo -e "$SUBNET$i\tip-${SUBNET//./-}$i" ;
done >> /etc/hosts
EOF
yum -y update
Note
R esu lt
A non-clustered JBoss EAP 6 managed domain has been configured, and launched on a Red Hat
AMI.
Report a bug
24 .5.2. Launch One or More Inst ances t o Serve as Host Cont rollers
Su mmary
This topic covers the steps required to launch one or more instances of JBoss EAP 6 to serve as
non-clustered host controllers on a Red Hat AMI (Amazon Machine Image).
611
Prereq u isit es
Configure and launch the non-clustered domain controller. Refer to Section 24.5.1, Launch an
Instance to Serve as a D omain Controller .
Pro ced u re 24 .4 . Lau n ch H o st C o n t ro llers
For each instance you would like to create, repeat the following steps:
1. Select an AMI.
2. D efine the desired number of instances (the number of slave host controllers).
3. Select the VPC and instance type.
4. Click on Security Group.
5. Ensure that all traffic from the JBoss EAP 6 subnet is allowed.
6. D efine other restrictions as desired.
7. Add the following into the User D ata field:
## mod cluster proxy addresses
MOD_CLUSTER_PROXY_LIST=10.0.0.4:7654
## host controller setup
### static domain controller discovery setup
JBOSS_DOMAIN_MASTER_ADDRESS=10.0.0.5
### S3 domain controller discovery setup
JBOSS_HOST_PASSWORD=<password for slave host controllers>
SUBNET=10.0.1.
####
JBOSS_HOST_USERNAME=admin
PORTS_ALLOWED="1024:65535"
## Server instance configuration
sed -i "s/other-server-group/main-server-group/"
$JBOSS_CONFIG_DIR/$JBOSS_HOST_CONFIG
612

for (( i=1 ; i<255 ; i++ )); do
done >> /etc/hosts
EOF
For further information on domain controller discovery on Amazon EC2, see Section 24.5.4,
Configuring D omain Controller D iscovery and Failover on Amazon EC2 .
yum -y update
Note
R esu lt
The JBoss EAP 6 non-clustered host controllers are configured and launched on a Red Hat AMI.
Report a bug
24 .5.3. T est t he Non-Clust ered JBoss EAP 6 Managed Domain

Su mmary
This topic covers the steps required to test the non-clustered JBoss EAP 6 managed domain on a
Red Hat AMI (Amazon Machine Image).
To test the managed domain you must know the elastic IP addresses of both the Apache HTTP server
and JBoss EAP 6 domain controller.
Prereq u isit es
Configure and launch the domain controller. See Section 24.5.1, Launch an Instance to Serve as
a D omain Controller .
Configure and launch the host controllers. See Section 24.5.2, Launch One or More Instances to
Serve as Host Controllers .
Pro ced u re 24 .5. T est t h e Web Server
Navigate to http: //ELAST IC _IP _O F_AP AC HE_HT T P D in a browser to confirm the web server
is running successfully.
Pro ced u re 24 .6 . T est t h e D o main C o n t ro ller
613
1. Navigate to http: //ELAST IC _IP _O F_D O MAIN_C O NT R O LLER : 9 9 9 0 /co nso l e

2. Log in using the username of ad mi n and the password specified in the User D ata field for the
domain controller and the admin console landing page for a managed domain should
appear
(http: //ELAST IC _IP _O F_D O MAIN_C O NT R O LLER : 9 9 9 0 /co nso l e/App. html #server
-i nstances).
3. Click the Server label at the top right side of the screen, and select any of the host controllers
in the Ho st dropdown menu at the top left side of the screen.
4. Verify that each host controller has two server configurations called server-o ne and
server-two and that they both belong to the mai n-server-g ro up.
5. Log out of the JBoss EAP 6 Admin Console.
Pro ced u re 24 .7. T est t h e H o st C o n t ro llers
1. Navigate to http: //ELASTIC_IP_OF_APACHE_HTTPD/hel l o to test that the sample
application is running successfully. The text Hel l o Wo rl d ! should appear in the browser.
If the text is not visible, refer here: Section 18.5.1, " About Troubleshooting Amazon EC2" .
2. Connect to the Apache HTTP server instance:
$ ssh -L7654:localhost:7654 ELASTIC_IP_OF_APACHE_HTTPD
3. Navigate to http: //l o cal ho st: 76 54 /mo d _cl uster-manag er to confirm all instances
are running correctly.
R esu lt
The JBoss EAP 6 web server, domain controller, and host controllers are running correctly on a Red
Hat AMI.
Report a bug
24 .5.4 . Configuring Domain Cont roller Discovery and Failover on Amaz on EC2
For a managed domain running on Amazon EC2, in addition to static domain controller discovery,
host controllers can dynamically discover a domain controller using the Amazon S3 storage system.
In particular, host controllers and the domain controller can be configured with information needed
to access an Amazon S3 bucket.
Using this configuration, when a domain controller is started, it writes its contact information to an S3
file in the bucket. Whenever a host controller attempts to contact the domain controller, it gets the
domain controller's contact information from the S3 file.
This means that if the domain controller's contact information changes (for example, it is common for
an EC2 instance's IP address to change when it is stopped and started), the host controllers do not
need to be reconfigured. The host controllers are able to get the domain controller's new contact
information from the S3 file.
You can automatically enable domain controller discovery by passing the
JBOSS_DOMAIN_S3_ACCESS_KEY, JBOSS_DOMAIN_S3_SECRET_ACCESS_KEY, and
JBOSS_DOMAIN_S3_BUCKET parameters to the JBoss EAP 6 instance when launching it. See
Section 24.10.1, Permanent Configuration Parameters for configurable parameters. Alternatively,
you can manually configure domain discovery using the following configuration.
614
The manual domain controller discovery configuration is specified using the following properties:
access- key
The Amazon AWS user account access key.
secret - access- key
The Amazon AWS user account secret access key.
lo cat io n
The Amazon S3 bucket to be used.
The following are example host controller and domain controller configurations. Although one
discovery option is shown in the examples below, it is possible to configure any number of static
discovery or S3 discovery options. For details on the domain discovery and failover process, see
Section 1.7, About D omain Controller D iscovery and Failover .
Examp le 24 .5. H o st C o n t ro ller C o n f ig u rat io n

<domain-controller>
<remote security-realm="ManagementRealm">
<discovery-options>
<discovery-option name="s3-discovery"
code="org.jboss.as.host.controller.discovery.S3Discovery"
module="org.jboss.as.host-controller">
<property name="access-key" value="S3_ACCESS_KEY"/>
<property name="secret-access-key"
value="S3_SECRET_ACCESS_KEY"/>
<property name="location" value="S3_BUCKET_NAME"/>
</discovery-option>
</remote>
Examp le 24 .6 . D o main C o n t ro ller C o n f ig u rat io n

<domain-controller>
<local>
<discovery-options>
<discovery-option name="s3-discovery"
code="org.jboss.as.host.controller.discovery.S3Discovery"
module="org.jboss.as.host-controller">
<property name="access-key" value="S3_ACCESS_KEY"/>
<property name="secret-access-key"
value="S3_SECRET_ACCESS_KEY"/>
<property name="location" value="S3_BUCKET_NAME"/>
</discovery-option>
</local>
615
Report a bug
24 .6. Clust ered JBoss EAP 6

24 .6.1. About Clust ered Inst ances
A clustered instance is an Amazon EC2 instance running JBoss EAP 6 with clustering enabled.
Another instance running the Apache HTTP server will be acting as the proxy for the instances in the
cluster.
The JBoss EAP 6 AMIs include two configuration files for use in clustered instances, stand al o neec2-ha. xml and stand al o ne-mo d _cl uster-ec2-ha. xml . Each of these configuration files
provides clustering without the use of multicast because Amazon EC2 does not support multicast.
This is done by using TCP unicast for cluster communications and S3_PING as the discovery
protocol. The stand al o ne-mo d _cl uster-ec2-ha. xml configuration also provides easy
registration with mod_cluster proxies.
Similarly, the d o mai n-ec2. xml configuration file provides two profiles for use in clustered
managed domains: ec2-ha, and mod_cluster-ec2-ha.
Report a bug
24 .6.2. About Virt ual Privat e Clouds

An Amazon Virtual Private Cloud (Amazon VPC) is a feature of Amazon Web Services (AWS) that
allows you to isolate a set of AWS resources in a private network. The topology and configuration of
this private network can be customized to your needs.
Refer to the Amazon Virtual Private Cloud website for more information http://aws.amazon.com/vpc/.
Report a bug
24 .6.3. Creat e a Virt ual Privat e Cloud (VPC)

Su mmary
This topic covers the steps required to create a Virtual Private Cloud, using a database external to
the VPC as an example. Your security policies may require connection to the database to be
encrypted. Please refer to Amazon's RDS FAQ for details about encrypting the database connections.
Important
VPC is recommended for a JBoss EAP 6 cluster setup as it greatly simplifies secure
communication between cluster nodes, a JON Server and the mod_cluster proxy. Without a
VPC, these communication channels need to be encrypted and authenticated.
For detailed instructions on configuring SSL, refer to the Core Management Security Guide .
1. Go to the VPC tab in the AWS console.

2. Subscribe to the service if needed.
3. Click on " C reate new VP C " .
616
4. Choose a VPC with one public and one private subnet.

a. Set the public subnet to be 10 . 0 . 0 . 0 /24 .
b. Set the private subnet to be 10 . 0 . 1. 0 /24 .
5. Go to El asti c IP s.
6. Create an elastic IP for use by the mod_cluster proxy/NAT instance.
7. Go to Securi ty g ro ups and create a security group to allow all traffic in and out.
8. Go to Network ACLs
a. Create an ACL to allow all traffic in and out.
b. Create an ACL to allow all traffic out and traffic in on only TCP ports 22, 80 0 9 , 80 80 ,
84 4 3, 9 4 4 3, 9 9 9 0 and 16 16 3.
R esu lt
The Virtual Private Cloud has been successfully created.
Report a bug
24 .6.4 . Launch an Apache HT T P Server Inst ance t o Serve as a mod_clust er

Proxy and a NAT Inst ance for t he VPC
Su mmary
This topic covers the steps required to launch an Apache HTTP server instance to serve as a
mod_cluster proxy and a NAT instance for the Virtual Private Cloud.
Prereq u isit es
Pro ced u re 24 .8. Lau n ch an Ap ach e H T T P server In st an ce t o Serve as a mo d _clu st er
p ro xy an d a N AT In st an ce f o r t h e VPC
1. Create an elastic IP for this instance.
2. Select an AMI.
3. Go to Securi ty G ro up and allow all traffic (use Red Hat Enterprise Linux's built-in firewall
capabilities to restrict access if desired).
4. Select " runni ng " in the public subnet of the VPC.
5. Select a static IP (e.g. 10 . 0 . 0 . 4 ).
6. Put the following in the User D ata: field:
JBOSSCONF=disabled
cat > $USER_SCRIPT << "EOS"
echo 1 > /proc/sys/net/ipv4/ip_forward
echo 0 > /proc/sys/net/ipv4/conf/all/rp_filter
617
echo 0 > /proc/sys/net/ipv4/conf/eth0/rp_filter

iptables -I INPUT 4 -s 10.0.1.0/24 -p tcp --dport 7654 -j ACCEPT
iptables -I INPUT 4 -p tcp --dport 80 -j ACCEPT
iptables -I FORWARD -m state --state RELATED,ESTABLISHED -j ACCEPT
iptables -I FORWARD -s 10.0.1.0/24 -j ACCEPT
iptables -t nat -A POSTROUTING -o eth0 ! -s 10.0.0.4 -j MASQUERADE
# balancer module incompatible with mod_cluster
sed -i -e 's/LoadModule proxy_balancer_module/#\0/'
/etc/httpd/conf/httpd.conf
cat > /etc/httpd/conf.d/mod_cluster.conf << "EOF"
#LoadModule proxy_module modules/mod_proxy.so
#LoadModule proxy_ajp_module modules/mod_proxy_ajp.so
LoadModule slotmem_module modules/mod_slotmem.so
LoadModule manager_module modules/mod_manager.so
LoadModule proxy_cluster_module modules/mod_proxy_cluster.so
LoadModule advertise_module modules/mod_advertise.so
Listen 7654
# workaround JBPAPP-4557
MemManagerFile /var/cache/mod_proxy/manager
<VirtualHost *:7654>
<Location /mod_cluster-manager>
SetHandler mod_cluster-manager
Order deny,allow
Deny from all
</Location>
<Location />
Order deny,allow
Deny from all
Allow from 10.
</Location>
KeepAliveTimeout 60
MaxKeepAliveRequests 0
ManagerBalancerName mycluster
ServerAdvertise Off
EnableMCPMReceive
</VirtualHost>
EOF
echo "`hostname | sed -e 's/ip-//' -e 'y/-/./'`
>> /etc/hosts
`hostname`"
semanage port -a -t http_port_t -p tcp 7654 #add port in the apache

port list for the below to work
setsebool -P httpd_can_network_relay 1 #for mod_proxy_cluster to
work
618
chcon -t httpd_config_t -u system_u

/etc/httpd/conf.d/mod_cluster.conf
#### Uncomment the following line when launching a managed domain
####
# setsebool -P httpd_can_network_connect 1
service httpd start
EOS
7. D isable the Amazon EC2 cloud source/destination checking for this instance so it can act as
a router.
a. Right-click on the running Apache HTTP server instance and choose " C hang e
So urce/D est check" .
b. Click on Y es, D i sabl e.
8. Assign the elastic IP to this instance.
R esu lt
The Apache HTTP server instance has been launched successfully.
Report a bug
24 .6.5. Configure t he VPC Privat e Subnet Default Rout e

Su mmary
This topic covers the steps required to configure the VPC private subnet default route. JBoss EAP 6
cluster nodes will run in the private subnet of the VPC, but cluster nodes require Internet access for
S3 connectivity. A default route needs to be set to go through the NAT instance.
Pro ced u re 24 .9 . C o n f ig u re t h e VPC Privat e Su b n et D ef au lt R o u t e
1. Navigate to the Apache HTTP server instance in the Amazon AWS console.
2. Navigate to the VPC ro u t e t ab les.
3. Click on the routing table used by the private subnet.
4. In the field for a new route enter 0 . 0 . 0 . 0 /0 .
5. Click on " Sel ect a targ et" .
6. Select " Enter Instance ID " .
7. Choose the ID of the running Apache HTTP server instance.
R esu lt
The default route has been successfully configured for the VPC subnet.
Report a bug
24 .6.6. About Ident it y and Access Management (IAM)
619
Identity and Access Management (IAM) provides configurable security for your AWS resources. IAM
can be configured to use accounts created in IAM or to provide identity federation between IAM and
your own identity services.
Refer to the AWS Identity and Access Management website for more information
http://aws.amazon.com/iam/.
Report a bug
24 .6.7. Configure IAM Set up

Su mmary
This topic covers the configuration steps required for setting up IAM for clustered JBoss EAP 6
instances. The S3_PING protocol uses an S3 bucket to discover other cluster members. JG ro u p s
version 3.0.x requires Amazon AWS account access and secret keys to authenticate against the S3
service.
Because S3 domain controller discovery makes use of an S3 bucket, it requires Amazon AWS
account access and secret keys to authenticate against the S3 service (similar to the S3_PING
protocol used by JGroups). The IAM user and S3 bucket used for S3 discovery must be different from
the IAM user and S3 bucket used for clustering.
It is a security risk to enter your main account credentials in the user-data field, store them online or
in an AMI. To circumvent this, a separate account can be created using the Amazon IAM feature
which would be only granted access to a single S3 bucket.
Pro ced u re 24 .10. C o n f ig u re IAM Set u p
1. Go to the IAM tab in the AWS console.
2. Click on users.
3. Select C reate New Users.
4. Choose a name, and ensure the G enerate an access key fo r each User option is
checked.
5. Select D o wnl o ad cred enti al s, and save them in a secure location.
6. Close the window.
7. Click on the newly created user.
8. Make note of the User AR M value. This value is required to set up the S3 bucket, documented
here: Section 24.6.9, Configure S3 Bucket Setup .
R esu lt
The IAM user account has been successfully created.
Report a bug
24 .6.8. About t he S3 Bucket

S3 Buckets are the basic organization store unit in the Amazon Simple Storage System (Amazon
S3). A bucket can store any number of arbitrary objects and must have a unique name to identify it
with Amazon S3..
620
Refer to the Amazon S3 website for more information, http://aws.amazon.com/s3/.

Report a bug
24 .6.9. Configure S3 Bucket Set up

Su mmary
This topic covers the steps required to configure a new S3 bucket.
Prereq u isit es
Section 24.6.7, Configure IAM Setup .
Pro ced u re 24 .11. C o n f ig u re S3 B u cket Set u p
1. Open the S3 tab in the AWS console.
2. Click on C reate Bucket.
3. Choose a name for the bucket and click C reate.
Note
Bucket names are unique across the entire S3. Names cannot be reused.
4. Right click on the new bucket and select P ro perti es.
5. Click Ad d bucket po l i cy in the permissions tab.
6. Click New po l i cy to open the policy creation wizard.
a. Copy the following content into the new policy, replacing
arn: aws: i am: : 0 5555555555: user/jbo sscl uster* with the value defined
here: Section 24.6.7, Configure IAM Setup . Change both instances of
cl usterbucket123 to the name of the bucket defined in step 3 of this procedure.
{
"Version": "2008-10-17",
"Id": "Policy1312228794320",
"Statement": [
{
"Sid": "Stmt1312228781799",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::055555555555:user/jbosscluster"
]
},
"Action": [
"s3:ListBucketVersions",
"s3:GetObjectVersion",
"s3:ListBucket",
"s3:PutBucketVersioning",
621
"s3:DeleteObject",
"s3:DeleteObjectVersion",
"s3:GetObject",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts",
"s3:PutObject",
"s3:GetBucketVersioning"
],
"Resource": [
"arn:aws:s3:::clusterbucket123/*",
"arn:aws:s3:::clusterbucket123"
]
}
]
}
R esu lt
A new S3 bucket has been created, and configured successfully.
Report a bug
24 .7. Clust ered Inst ances

24 .7.1. Launch Clust ered JBoss EAP 6 AMIs
Su mmary
This topic covers the steps required to launch clustered JBoss EAP 6 AMIs.
Prereq u isit es
Section 24.6.3, Create a Virtual Private Cloud (VPC) .
NAT Instance for the VPC .
Section 24.6.5, Configure the VPC Private Subnet D efault Route .
Section 24.6.7, Configure IAM Setup .
Section 24.6.9, Configure S3 Bucket Setup .
Warning
Running a JBoss EAP 6 cluster in a subnet with network mask smaller than 24 bits or
spanning multiple subnets complicates acquiring a unique server peer ID for each cluster
member.
Refer to the JBOSS_CLUSTER_ID variable for information on how to make such a
configuration work reliably: Section 24.10.1, Permanent Configuration Parameters .
622
Important
The auto-scaling Amazon EC2 feature can be used with JBoss EAP 6 cluster nodes. However,
ensure it is tested b ef o re deployment. You should ensure that your particular workloads
scale to the desired number of nodes, and that the performance meets your needs for the
instance type you are planning to use (different instance types receive a different share of the
EC2 cloud resources).
Furthermore, instance locality and current network/storage/host machine/RD S utilization can
affect performance of a cluster. Test with your expected real-life loads and try to account for
unexpected conditions.
Warning
The Amazon EC2 scale-down action terminates the nodes without any chance to gracefully
shut down, and, as some transactions might be interrupted, other cluster nodes (and load
balancers) will need time to fail over. This is likely to impact your application users'
experience.
It is recommended that you either scale down the application cluster manually by disabling the
server from the mod_cluster management interface until processed sessions are completed, or
shut down the JBoss EAP 6 instance gracefully (SSH access to the instance or JON can be
used).
Test that your chosen procedure for scaling-down does not lead to adverse effects on your
users' experience. Additional measures might be required for particular workloads, load
balancers and setups.
Pro ced u re 24 .12. Lau n ch C lu st ered JB o ss EAP 6 AMIs

1. Select an AMI.
2. D efine the desired number of instances (the cluster size).
4. Click on Securi ty G ro up.
5. Ensure that all traffic from the JBoss EAP 6 cluster subnet is allowed.
Examp le 24 .7. Examp le U ser D at a Field

## clustering setup
JBOSS_JGROUPS_S3_PING_SECRET_ACCESS_KEY=<your secret key>
623
JBOSS_JGROUPS_S3_PING_ACCESS_KEY=<your access key>

JBOSS_JGROUPS_S3_PING_BUCKET=<your bucket name>
## password to access admin console
JBOSSAS_ADMIN_PASSWORD=<your password for opening admin console>
## database credentials configuration
JAVA_OPTS="$JAVA_OPTS Ddb.host=instancename.something.rds.amazonaws.com Ddb.database=mydatabase -Ddb.user=<user> -Ddb.passwd=<pass>"
SUBNET=10.0.1.
####
name>.war
## install the JDBC driver as a core module
yum -y install mysql-connector-java
mkdir -p /usr/share/jbossas/modules/com/mysql/main
cp -v /usr/share/java/mysql-connector-java-*.jar
/usr/share/jbossas/modules/com/mysql/main/mysql-connectorjava.jar
cat > /usr/share/jbossas/modules/com/mysql/main/module.xml
<<"EOM"
<resources>
<resource-root path="mysql-connector-java.jar"/>
</resources>
<dependencies>
</dependencies>
</module>
EOM
cat > $USER_CLI_COMMANDS << "EOC"
## Deploy sample application from local filesystem
deploy --force /usr/share/java/jboss-ec2-eap-samples/clusterdemo.war
## ExampleDS configuration for MySQL database
data-source remove --name=ExampleDS
/subsystem=datasources/jdbc-driver=mysql:add(drivername="mysql",driver-module-name="com.mysql")
624
data-source add --name=ExampleDS --connectionurl="jdbc:mysql://${db.host}:3306/${db.database}" --jndiname=java:jboss/datasources/ExampleDS --driver-name=mysql --username="${db.user}" --password="${db.passwd}"

/subsystem=datasources/data-source=ExampleDS:enable
/subsystem=datasources/data-source=ExampleDS:test-connection-inpool
EOC
for (( i=1 ; i<255 ; i++ )); do
done >> /etc/hosts
EOF
R esu lt
The clustered JBoss EAP 6 AMIs have been configured and launched successfully.
Report a bug
24 .7.2. T est t he Clust ered JBoss EAP 6 Inst ance

Su mmary
This topic covers the steps to confirm that the clustered JBoss EAP 6 instances are running correctly.
Pro ced u re 24 .13. T est in g t h e C lu st ered In st an ce
1. Navigate to http://ELASTIC_IP_OF_APACHE_HTTPD in a browser to confirm the web server is
running successfully.
2. T est t h e C lu st ered N o d es
a. Navigate to http://ELASTIC_IP_OF_APACHE_HTTPD /cluster-demo/put.jsp in a
browser.
b. Verify that one of the cluster nodes logs the following message:
Putting date now
c. Stop the cluster node that logged the message in the previous step.
d. Navigate to http://ELASTIC_IP_OF_APACHE_HTTPD /cluster-demo/get.jsp in a
browser.
e. Verify that the time shown is the same as the time that was PUT using put. jsp in
Step 2-a.
f. Verify that one of the running cluster nodes logs the following message:
625
Getting date now

g. Restart the stopped clustered node.
h. Connect to the Apache HTTP server instance:
ssh -L7654:localhost:7654 <ELASTIC_IP_OF_APACHE_HTTPD>
i. Navigate to http://localhost:7654/mod_cluster-manager to confirm all instances are
running correctly.
R esu lt
The clustered JBoss EAP 6 instances have been tested, and confirmed to be working correctly.
Report a bug
24 .8. Clust ered Managed Domains

24 .8.1. Launch an Inst ance t o Serve as a Clust er Domain Cont roller
Su mmary
This topic covers the steps required to launch a clustered JBoss EAP 6 managed domain on a Red
Hat AMI (Amazon Machine Image).
Prereq u isit es
NAT Instance for the VPC
Section 24.6.5, Configure the VPC Private Subnet D efault Route
Pro ced u re 24 .14 . Lau n ch a C lu st er D o main C o n t o ller
1. Create an elastic IP for this instance.
2. Select an AMI.
3. Go to Security Group and allow all traffic (use Red Hat Enterprise Linux's built-in firewall
capabilities to restrict access if desired).
4. Choose " running" in the public subnet of the VPC.
5. Choose a static IP (e.g. 10 . 0 . 0 . 5).
6. Put the following in the User D ata: field:
626

## password that will be used by slave host controllers to connect
to the domain controller
JBOSSAS_ADMIN_PASSWORD=<password for slave host controllers>
SUBNET=10.0.0.
## S3 domain controller discovery setup
####
JBOSS_DOMAIN_CONTROLLER=true
PORTS_ALLOWED="9999 9990 9443"
# wget https://<your secure storage hostname>/<path>/<app name>.war
-O /usr/share/java/jboss-ec2-eap-applications/<app name>.war
## Install the JDBC driver as a core module
/usr/share/jbossas/modules/com/mysql/main/mysql-connector-java.jar
cat > /usr/share/jbossas/modules/com/mysql/main/module.xml <<"EOM"
<resources>
</resources>
<dependencies>
</dependencies>
</module>
EOM
cat > $USER_CLI_COMMANDS << "EOC"
## Deploy the sample application from the local filesystem
deploy /usr/share/java/jboss-ec2-eap-samples/cluster-demo.war -server-groups=other-server-group
## ExampleDS configuration for MySQL database
data-source --profile=mod_cluster-ec2-ha remove --name=ExampleDS
/profile=mod_cluster-ec2-ha/subsystem=datasources/jdbcdriver=mysql:add(driver-name="mysql",driver-modulename="com.mysql")
627
data-source --profile=mod_cluster-ec2-ha add --name=ExampleDS -connection-url="jdbc:mysql://${db.host}:3306/${db.database}" -jndi-name=java:jboss/datasources/ExampleDS --driver-name=mysql -user-name="${db.user}" --password="${db.passwd}"

/profile=mod_cluster-ec2-ha/subsystem=datasources/datasource=ExampleDS:enable
EOC
for (( i=1 ; i<255 ; i++ )); do
done >> /etc/hosts
EOF
yum -y update
Note
R esu lt
A clustered JBoss EAP 6 managed domain is configured and launched on a Red Hat AMI.
Report a bug
24 .8.2. Launch One or More Inst ances t o Serve as Clust er Host Cont rollers
Su mmary
This topic covers the steps required to launch one or more instances of JBoss EAP 6 to serve as
cluster host controllers on a Red Hat AMI (Amazon Machine Image).
Prereq u isit es
Configure and launch the cluster domain controller. Refer to Section 24.8.1, Launch an Instance
to Serve as a Cluster D omain Controller .
628
Pro ced u re 24 .15. Lau n ch H o st C o n t ro llers

For each instance you would like to create, repeat the following steps:
1. Select an AMI.
2. D efine the desired number of instances (the number of slave host controllers).
4. Click on Security Group.
5. Ensure that all traffic from the JBoss EAP 6 cluster subnet is allowed.
## clustering setup
JBOSS_JGROUPS_S3_PING_SECRET_ACCESS_KEY=<your secret key>
JBOSS_JGROUPS_S3_PING_ACCESS_KEY=<your access key>
JBOSS_JGROUPS_S3_PING_BUCKET=<your bucket name>
## host controller setup
### static domain controller discovery setup
JBOSS_DOMAIN_MASTER_ADDRESS=10.0.0.5
### S3 domain controller discovery setup
JBOSS_HOST_PASSWORD=<password for slave host controllers>
## database credentials configuration
JAVA_OPTS="$JAVA_OPTS Ddb.host=instancename.something.rds.amazonaws.com Ddb.database=mydatabase -Ddb.user=<user> -Ddb.passwd=<pass>"
SUBNET=10.0.1.
####
JBOSS_HOST_USERNAME=admin
## Server instance configuration
sed -i "s/main-server-group/other-server-group/"
$JBOSS_CONFIG_DIR/$JBOSS_HOST_CONFIG
## install the JDBC driver as a core module
629
/usr/share/jbossas/modules/com/mysql/main/mysql-connector-java.jar
cat > /usr/share/jbossas/modules/com/mysql/main/module.xml <<"EOM"
<resources>
</resources>
<dependencies>
</dependencies>
</module>
EOM
for (( i=1 ; i<255 ; i++ )); do
done >> /etc/hosts
EOF
yum -y update
Note
R esu lt
The JBoss EAP 6 cluster host controllers are configured and launched on a Red Hat AMI.
Report a bug
24 .8.3. T est t he Clust ered JBoss EAP 6 Managed Domain

Su mmary
This topic covers the steps required to test the clustered JBoss EAP 6 managed domain on a Red Hat
AMI (Amazon Machine Image).
630
To test the Managed D omain you must know the elastic IP addresses of both the Apache HTTP
server and JBoss EAP 6 D omain Controller.
Prereq u isit es
Configure and launch the cluster domain controller. See Section 24.8.1, Launch an Instance to
Serve as a Cluster D omain Controller .
Configure and launch the cluster host controllers. See Section 24.8.2, Launch One or More
Instances to Serve as Cluster Host Controllers .
Pro ced u re 24 .16 . T est t h e Ap ach e H T T P server in st an ce
Navigate to http: //ELASTIC_IP_OF_APACHE_HTTP_SERVER in a browser to confirm the web
server is running successfully.
Pro ced u re 24 .17. T est t h e D o main C o n t ro ller
1. Navigate to http: //ELASTIC_IP_OF_DOMAIN_CONTROLLER: 9 9 9 0 /co nso l e
2. Log in using the username ad mi n and the password specified in the User D ata field for the
domain controller. Once logged in, the administration console landing page for a managed
domain should appear
(http: //ELASTIC_IP_OF_DOMAIN_CONTROLLER: 9 9 9 0 /co nso l e/App. html #serveri nstances).
3. Click the Server label at the top right side of the screen. Select any of the host controllers in
the Ho st dropdown menu at the top left side of the screen.
4. Verify that this host controller has two server configurations called server-o ne and
server-two and verify that they both belong to the o ther-server-g ro up.
Pro ced u re 24 .18. T est t h e H o st C o n t ro llers
1. Navigate to http: //ELASTIC_IP_OF_APACHE_HTTP_SERVER/cl uster-d emo /put. jsp
in a browser.
2. Verify that one of the host controllers logs the following message: P utti ng d ate no w.
3. Stop the server instance that logged the message in the previous step (see Stop a Server Using
the Management Console).
4. Navigate to http: //ELASTIC_IP_OF_APACHE_HTTP_SERVER/cl uster-d emo /g et. jsp
in a browser.
5. Verify that the time shown is the same as the time that was P UT using put. jsp in Step 2.
6. Verify that one of the running server instances logs the following message: G etti ng d ate
no w.
7. Restart the stopped server instance (see Section 2.3.2, Start a Server Using the Management
Console )
8. Connect to the Apache HTTP server instance.
$ ssh -L7654:localhost:7654 ELASTIC_IP_OF_APACHE_HTTP_SERVER
9. Navigate to http: //l o cal ho st: 76 54 /mo d _cl uster-manag er to confirm all instances
are running correctly.
631
R esu lt
The JBoss EAP 6 web server, domain controller, and host controllers are running correctly on a Red
Hat AMI.
Report a bug
24 .9. Est ablishing Monit oring wit h JBoss Operat ions Net work (JON)
24 .9.1. About AMI Monit oring
With your business application deployed to a correctly-configured AMI instance, the next step is to
establish monitoring of the platform with JBoss Operations Network (JON).
The JON server is commonly located inside a corporate network, so it's necessary to establish a
secure connection between the server and each of its agents. Establishing a VPN between the two
points is the most common solution but this complicates the required networking configuration. This
chapter provides network configuration guidelines for enabling communication between the JON
agent and JON server. For more extensive information on configuration, management, and usage
please refer to the official Red Hat documentation for JBoss Operations Network (JON).
Fig u re 24 .1. JO N Server co n n ect ivit y

Report a bug
24 .9.2. About Connect ivit y Requirement s
632
Registering a JON agent with its servers requires two-way communication between agent and
servers. The JON Agent needs access to port 70 80 on all JON servers, except in the case of SSL
where port 74 4 3 is used. Each JON server must be able to access each of the connected agents on a
unique host and port pairing. The agent port is usually 16 16 3.
If there are multiple clustered JON servers, make sure each agent can communicate with all servers in
the JON cluster via the IP and hostname pairs as configured through the JON server administration
console. The JON server used by the agent to register may not be the server it tries to use after
initialization.
Report a bug
24 .9.3. About Net work Address T ranslat ion (NAT )

A corporate VPN gateway acting in routed mode greatly simplifies network configuration. If your
corporate VPN gateway is acting in NAT mode however, the JON server does not have direct visibility
of agents. In this case, port forwarding needs to be configured for each agent.
NAT VPN configurations require a port on the gateway to be forwarded to the JON agent's address of
port on the managed machine. The JON agent also needs to be configured to tell the server the
forwarded port number and IP address. You can find further information in the
rhq . co mmuni cati o ns. co nnecto r. * description for the ag ent-co nfi g urati o n. xml
configuration file.
Report a bug
24 .9.4 . About Amaz on EC2 and DNS

JON servers and JON agents need to be able to resolve each others' hostnames. The D NS resolution
is more complicated in the case of a VPN configuration. Connected servers have multiple possible
options. One option is to use either the Amazon EC2 or the corporate network's D NS servers. Another
option is to use a split D NS configuration where the corporate D NS servers are used for resolving
names in particular domains, and the Amazon EC2 D NS servers are used for resolving all other
names.
Report a bug
24 .9.5. About Rout ing in EC2

All Amazon EC2 servers have a so urce/d esti nati o n checki ng routing feature activated by
default. This feature drops any packets being sent to the server which have a destination different
from the machine's IP address. If the VPN solution selected for connecting agents to the JON server
includes a router, this feature needs to be turned off for the server or servers acting as routers or VPN
gateways. This configuration setting can be accessed via the Amazon AWS console. D isabled
so urce/d esti nati o n checki ng is also required in a Virtual Private Cloud (VPC).
Some VPN configurations route general Internet traffic through the corporate VPN by default. It is
recommended that you avoid this as it may be a slower and less efficient configuration for your
particular needs.
While the use of a proper addressing schema is not a concern specific to JON, poor schemas can
affect it. Amazon EC2 assigns IP addresses from the 10 . 0 . 0 . 0 /8 network. Instances usually have
a public IP address also, but only network traffic on the internal IP address within the same
availability zone is free. To avoid using the 10 . 0 . 0 . 0 /8 network in private addressing, there are a
few things to consider.
633
When creating a VPC, avoid allocating addresses already in use in the private network to avoid
connectivity problems.
If an instance needs access to availability zone local resources, make sure Amazon EC2 private
addresses are used and traffic is not routed through the VPN.
If an Amazon EC2 instance will access a small subset of corporate private network addresses (for
example only JON servers), only these addresses should be routed through the VPN. This
increases security and lowers the chance of Amazon EC2 or private network address space
collisions.
Report a bug
24 .9.6. About T erminat ing and Rest art ing wit h JON
One of the benefits of a cloud environment is the ease by which you can terminate and launch a
machine instance. You can also launch an instance identical to the initial one. This may cause
issues if the new instance tries to register with JON servers using the same agent name as the
previously running agent. If this happens the JON server will not allow an agent to reconnect with a
missing or non-matching identification token.
To avoid this, ensure that terminated agents are removed from the JON inventory before trying to
connect an agent with the same name or specify the correct identification token when starting new
agent.
Another issue that you might encounter is when an agent machine is assigned a new VPN IP address
that no longer matches the address recorded in the JON configuration. An example might include a
machine that is restarted or where a VPN connection is terminated. In this case, it is recommended
that you bind the JON agent's life cycle to the VPN connection's life cycle. If the connection drops,
you can stop the agent. When the connection is restored again, update JO N_AG ENT _AD D R in
/etc/sysco nfi g /jo n-ag ent-ec2 to reflect the new IP address and restart the agent.
Information on how to change the agent's IP address can be found in the Configuring JON Servers
and Agents Guide available at https://access.redhat.com/documentation/enUS/JBoss_Operations_Network.
If there are a high number of instances launched and/or terminated it can become impractical to add
and remove them manually from the JON inventory. JON's scripting capabilities can be used for
automate these steps. Refer to the JON documentation for further information.
Report a bug
24 .9.7. Configure an Inst ance t o Regist er wit h JBoss Operat ions Net work
Use the following procedure to register a JBoss EAP 6 instance with JBoss Operations Network.
For JBoss EAP 6, add this to the User D ata field.
JON_SERVER_ADDR=jon2.it.example.com
## if instance not already configured to resolve its hostname
JON_AGENT_ADDR=ìp addr show dev eth0 primary to 0/0 | sed -n
's#.*inet $[0-9.]\+$/.*#\1#p'`
PORTS_ALLOWED=16163
# insert other JON options when necessary.
See Section 24.10.1, Permanent Configuration Parameters , parameters starting with JON_ for
the format of JON options.
634
Report a bug
24 .10. User Script Configurat ion

24 .10.1. Permanent Configurat ion Paramet ers
Su mmary
The following parameters can be used to influence the configuration and operation of JBoss EAP 6.
Their contents are written to /etc/sysco nfi g /jbo ssas and /etc/sysco nfi g /jo n-ag entec2.
T ab le 24 .2. C o n f ig u rab le Paramet ers
N ame
D escrip t io n
D ef au lt
JBOSS_JGROUPS_S3_PING_
ACCESS_KEY
Amazon AWS user account

access key for S3_PING
discovery if clustering is used.
secret access key.
Amazon S3 bucket to be used
for S3_PING discovery.
ID of cluster member nodes.
Only used for clustering.
Accepted values are (in order):
N/A
SECRET_ACCESS_KEY
BUCKET
JBOSS_CLUSTER_ID
N/A
N/A
Last octet of eth0's IP address
A valid cluster ID number in

the range 0 - 10 23.
A network interface name,
where the last octet of the IP
is used as the value.
" S3" as a value would
coordinate ID usage
through the S3 bucket used
by jgroups' S3_PING.
It is recommended to use the
last octet of the IP (the
default) when all cluster
nodes are located in the
same 24 or more bit subnet
(for example, in a VPC
subnet).
MOD _CLUSTER_PROXY_LIST
PORTS_ALLOWED
JBOSSAS_AD MIN_PASSWOR
D
Comma-delimited list of
IPs/hostnames of mod_cluster
proxies if mod_cluster is to be
used.
List of incoming ports to be
allowed by firewall in addition
to the default ones.
Password for the ad mi n user.
N/A
N/A
N/A
635
N ame
D escrip t io n
D ef au lt
JON_SERVER_AD D R
JON server hostname or IP with

which to register. This is only
used for registration, after that
the agent may communicate
with other servers in the JON
cluster.
Port used by the agent to
communicate with the server.
Name of JON agent, must be
unique.
Port that the agent listens on.
IP address that the JON agent
is to be bound to. This is used
when the server has more than
one public address, (e.g. VPN).
Additional JON agent system
properties which can be used
for configuring SSL, NAT and
other advanced settings.
Name of JBoss EAP 6 server
configuration file to use. If
JBOSS_D OMAIN_CONTROLLE
R=true, then d o mai nec2. xml is used. Otherwise:
N/A
JON_SERVER_PORT
JON_AGENT_NAME
JON_AGENT_PORT
JON_AGENT_AD D R
JON_AGENT_OPTS
JBOSS_SERVER_CONFIG
If S3 config is present, then

stand al o ne-ec2ha. xml is used.
If
MOD _CLUSTER_PROXY_LI
ST is specified, then
stand al o nemo d _cl uster-ec2ha. xml is selected.
If neither of the first two
options are used, then the
stand al o ne. xml file is
used.
Can also be set to
stand al o ne-ful l . xml .
JAVA_OPTS
JBOSS_IP
JBOSSCONF
R
636
Custom values to be added to

the variable before JBoss EAP
6 starts.
IP address that the server is to
be bound to.
The name of the JBoss EAP 6
profile to start. To prevent
JBoss EAP 6 from starting,
JBOSSCONF can be set to
d i sabl ed
Sets whether or not this
instance will run as a domain
controller.
7080
Instance's ID
16163
JON agent chooses the IP of
local hostname by default.
N/A
stand al o ne. xml ,

stand al o ne-ful l . xml ,
stand al o ne-ec2-ha. xml ,
stand al o ne-mo d _cl userec2-ha. xml , d o mai nec2. xml depending on the
other parameters.
JAVA_OPTS is built from the

values of other parameters.
127.0.0.1
stand al o ne
fal se
N ame
D escrip t io n
D ef au lt
JBOSS_D OMAIN_MASTER_AD
D RESS
JBOSS_HOST_NAME
IP address of remote domain

controller.
The logical host name (within
the domain). This needs to be
distinct.
The username the host
controller should use when
registering with the domain
controller. If not provided, the
JBOSS_HOST_NAME is used
instead.
The password the host
controller should use when
registering with the domain
controller.
If
R=true, then ho stmaster. xml is used. If
JBOSS_D OMAIN_MASTER_AD
D RESS is present, then ho stsl ave. xml is used.
access key for S3 domain
controller discovery.
secret access key for S3
domain controller discovery.
Amazon S3 bucket to be used
for S3 domain controller
discovery.
N/A
JBOSS_HOST_USERNAME
JBOSS_HOST_PASSWORD
JBOSS_HOST_CONFIG
JBOSS_D OMAIN_S3_ACCESS
_KEY
JBOSS_D OMAIN_S3_SECRET
_ACCESS_KEY
JBOSS_D OMAIN_S3_BUCKET
The value of the HOSTNAME

environment variable.
JBOSS_HOST_NAME
N/A
ho st-master. xml or ho stsl ave. xml , depending on the

other parameters.
N/A
N/A
N/A
Report a bug
24 .10.2. Cust om Script Paramet ers

Su mmary
The following parameters can be used in the user customization section of the User D ata: field.
T ab le 24 .3. C o n f ig u rab le Paramet ers
N ame
D escrip t io n
JBOSS_D EPLOY_D IR
D eploy directory of the active profile (for example,

/var/l i b/jbo ssas/stand al o ne/d epl o yments/).
D eployable archives placed in this directory will be deployed.
Red Hat recommends using the Management Console or CLI tool
to manage deployments instead of using the deploy directory.
Config directory of the active profile (for example,
/var/l i b/jbo ssas/stand al o ne/co nfi g urati o n).
JBOSS_CONFIG_D IR
637
N ame
D escrip t io n
JBOSS_HOST_CONFIG
Name of the active host configuration file (for example, ho stmaster. xml ). Red Hat recommends using the Management
Console or CLI tools to configure the server instead of editing the
configuration file.
Name of the active server configuration file (for example,
stand al o ne-ec2-ha. xml ). Red Hat recommends using the
Management Console or CLI tools to configure the server instead
of editing the configuration file.
Path to the custom configuration script, which is available prior
to sourcing user-data configuration.
Path to a custom file of CLI commands, which is available prior to
sourcing user-data configuration.
JBOSS_SERVER_CONFIG
USER_SCRIPT
USER_CLI_COMMAND S
Report a bug
24 .11. T roubleshoot ing

24 .11.1. About T roubleshoot ing Amaz on EC2
EC2 provides an Alarm Status for each instance, indicating severe instance malfunction but the
absence of such an alarm is no guarantee that the instance has started correctly and services are
running properly. It is possible to use Amazon CloudWatch with its custom metric functionality to
monitor instance services' health but use of an enterprise management solution is recommended.
To simplify troubleshooting, Red Hat recommends managing the EC2 instance using JBoss
Operations Network (JON) which can automatically discover, monitor and manage many services on
an EC2 instance with the JON agent installed, including: JBoss EAP 6, Tomcat, Apache HTTP Server,
and PostgreSQL. For details of monitoring JBoss EAP with JON, see Section 24.9.1, About AMI
Monitoring .
Report a bug
24 .11.2. Diagnost ic Informat ion

In case of a problem being detected by the JBoss Operations Network, Amazon CloudWatch or
manual inspection, common sources of diagnostic information are:
/var/l o g /jbo ss_user-d ata. o ut is the output of the jboss-ec2-eap init script and user
custom configuration script.
/var/cache/jbo ss-ec2-eap/ contains the actual user data, custom script, and custom CLI
commands used at instance start-up.
/var/l o g also contains all the logs collected from machine start up, JBoss EAP 6, httpd and
most other services.
Access to these files is only available via an SSH session. Refer to the Amazon EC Getting Started
Guide for details on how to configure and establish an SSH session with an Amazon EC2 instance.
Report a bug
638
Chapter 25. Externalize Sessions

25.1. Ext ernaliz e HT T P Session from JBoss EAP 6.x t o JBoss Dat a
Grid
Red Hat JBoss D ata Grid can be used as an external cache container for application specific data in
JBoss Enterprise Application Platform (EAP), such as HTTP Sessions. This allows scaling of the
data layer independent of the application, and enables different EAP clusters, that may reside in
various domains, to access data from the same JBoss D ata Grid cluster. Additionally, other
applications can interface with the caches presented by Red Hat JBoss D ata Grid.
The below procedure applies for both standalone and domain mode of EAP; however, in domain
mode each server group requires a unique remote cache configured. While multiple server groups
can utilize the same Red Hat JBoss D ata Grid cluster the respective remote caches will be unique to
the EAP server group.
Note
For each distributable application, an entirely new cache must be created. It can be created in
an existing cache container, for example, web.
Pro ced u re 25.1. Ext ern aliz e H T T P Sessio n s

1. Ensure the remote cache containers are defined in EAP's i nfi ni span subsystem; in the
example below the cache attribute in the remo te-sto re element defines the cache name on
the remote JBoss D ata Grid server:
<subsystem xmlns="urn:jboss:domain:infinispan:1.5">
[...]
<cache-container name="cacheContainer" default-cache="defaultcache" module="org.jboss.as.clustering.web.infinispan" statisticsenabled="true">
<replicated-cache name="default-cache" mode="SYNC"
batching="true">
<remote-store cache="default" socket-timeout="60000"
preload="true" passivation="false" purge="false" shared="true">
<remote-server outbound-socket-binding="remote-jdgserver1"/>
<remote-server outbound-socket-binding="remote-jdgserver2"/>
</remote-store>
</replicated-cache>
</cache-container>
</subsystem>
2. D efine the location of the remote Red Hat JBoss D ata Grid server by adding the networking
information to the so cket-bi nd i ng -g ro up:
<socket-binding-group ...>
<outbound-socket-binding name="remote-jdg-server1">
<remote-destination host="JDGHostName1" port="11222"/>
639
<outbound-socket-binding name="remote-jdg-server2">
<remote-destination host="JDGHostName2" port="11222"/>
3. Repeat the above steps for each cache-container and each Red Hat JBoss D ata Grid server.
Each server defined must have a separate <o utbo und -so cket-bi nd i ng > element
defined.
4. Add passivation and cache information into the application's jbo ss-web. xml . In the
following example cacheC o ntai ner is the name of the cache container, and d efaul tcache is the name of the default cache located in this container. An example file is shown
below:
<jboss-web version="6.0"
xmlns="http://www.jboss.com/xml/ns/javaee"
http://www.jboss.org/j2ee/schema/jboss-web_6_0.xsd">
<replication-config>
<replication-trigger>SET</replication-trigger>
<replication-granularity>SESSION</replication-granularity>
<cache-name>cacheContainer.default-cache</cache-name>
</replication-config>
<passivation-config>
<use-session-passivation>true</use-session-passivation>
<passivation-min-idle-time>900</passivation-min-idle-time>
<passivation-max-idle-time>1800</passivation-max-idle-time>
</passivation-config>
</jboss-web>
Note
The passivation timeouts above are provided assuming that a typical session is
abandoned within 15 minutes and uses the default HTTP session timeout in JBoss
EAP of 30 minutes. These values may need to be adjusted based on each
application's workload.
Report a bug
64 0
Chapt er 2 5. Ext ernaliz e Sessions
Appendix A. Supplemental References

A.1. Download Files from t he Red Hat Cust omer Port al
Prereq u isit es
Before you begin this task, you need a Customer Portal account. Browse to
https://access.redhat.com and click the R eg i ster link in the upper right corner to create an
account.
Pro ced u re A.1. Lo g in an d D o wn lo ad Files f ro m t h e R ed H at C u st o mer Po rt al
1. Browse to https://access.redhat.com and click the Lo g i n link in the top right corner. Enter
your credentials and click Lo g In.
R esu lt
You are logged into RHN and you are returned to the main web page at
2. N avig at e t o t h e D o wnl o ad s p ag e.
Use one of the following options to navigate to the D o wnl o ad s page.
A. Click the D o wnl o ad s link in the top navigation bar.
B. Navigate directly to https://access.redhat.com/downloads/.
3. Select t h e p ro d u ct an d versio n t o d o wn lo ad .
Use one of the following ways to choose the correct product and version to download.
A. Step through the navigation one level at a time.
B. Search for your product using the search area at the top right-hand side of the screen.
4. D o wn lo ad t h e ap p ro p riat e f ile f o r yo u r o p erat in g syst em an d in st allat io n met h o d
o f ch o ice.
D epending on the product you choose, you may have the choice of a Z ip archive, RPM, or
native installer for a specific operating system and architecture. Click either the file name or
the D o wnl o ad link to the right of the file you want to download.
R esu lt
The file is downloaded to your computer.
Report a bug
A.2. Configure t he Default Java Development Kit on Red Hat Ent erprise
Linux
It is possible to have multiple Java development kits installed on your Red Hat Enterprise Linux
system. This task shows you how to specify which one your current environment uses. It uses the
al ternati ves command.
64 1
Important
This task only applies to Red Hat Enterprise Linux.
Note
It may not be necessary to do this step. Red Hat Enterprise Linux uses OpenJD K 1.6 as the
default option. If this is what you want, and your system is working properly, you do not need
to manually specify which Java development kit to use.
Prereq u isit es
In order to complete this task, you need to have superuser access, either through direct login or
by means of the sud o command.
Pro ced u re A.2. C o n f ig u re t h e D ef au lt Java D evelo p men t K it
1. D et ermin e t h e p at h s f o r yo u r p ref erred java an d javac b in aries.
You can use the command rpm -q l packagename | g rep bin to find the locations of
binaries installed from RPMs. The default locations of the java and javac binaries on Red
Hat Enterprise Linux 32-bit systems are as follows.
T ab le A.1. D ef au lt lo cat io n s f o r java an d javac b in aries
Java D evelo p men t K it
Pat h
OpenJD K 1.6
/usr/l i b/jvm/jre-1. 6 . 0 o penjd k/bi n/java

/usr/l i b/jvm/java-1. 6 . 0 o penjd k/bi n/javac
Oracle JD K 1.6
/usr/l i b/jvm/jre-1. 6 . 0 sun/bi n/java

/usr/l i b/jvm/java-1. 6 . 0 sun/bi n/javac
2. Set t h e alt ern at ive yo u wish t o u se f o r each .

Run the following commands to set your system to use a specific java and javac:
/usr/sbi n/al ternati ves --co nfi g java or /usr/sbi n/al ternati ves --co nfi g
javac. Follow the on-screen instructions.
3. O p t io n al: Set t h e java_sd k_1. 6 . 0 alt ern at ive ch o ice.
If you want to use Oracle JD K, you need to set the alternative for java_sd k_1. 6 . 0 . as well.
Use the following command: /usr/sbi n/al ternati ves --co nfi g java_sd k_1. 6 . 0 .
The correct path is usually /usr/l i b/jvm/java-1. 6 . 0 -sun. You can do a file listing to
verify it.
64 2
Appendix A. Supplement al References
R esu lt :
The alternative Java D evelopment Kit is selected and active.
Report a bug
A.3. Management Int erface Audit Logging Reference

Lo g g er At t rib u t es R ef eren ce
In addition to enabling or disabling management interface audit logging, the following l o g g er
configuration attributes are available.
lo g - b o o t
If set to true, management operations when booting the server are included in the audit
log, fal se otherwise. D efault: true.
lo g - read - o n ly
If set to true, all operations will be audit logged. If set to fal se only operations that
change the model will be logged. D efault: fal se.
Lo g Fo rmat t er At t rib u t es R ef eren ce
The formatter specifies the format of the log entries. Only one formatter is available, which outputs log
entries in JSON format.
Examp le A.1. In clu d e t h e t imest amp in t h e lo g reco rd s

/core-service=management/access=audit/json-formatter=jsonformatter:write-attribute(name=include-date,value=true)
Lo g Fo rmat t er At t rib u t es
in clu d e- d at e
A boolean value which defines whether or not the timestamp is included in the formatted log
records. D efault: true.
d at e- sep arat o r
A string containing characters to be used to separate the date and the rest of the formatted
log message. This is ignored if include-date=fal se. D efault: (This is a space,
followed by a hyphen, then a space).
d at e- f o rmat
The date format to use for the timestamp as understood by java.text.SimpleD ateFormat.
Ignored if include-date=fal se. D efault: yyyy-MM-d d HH: mm: ss.
co mp act
If true it will format the JSON on one line. There may still be values containing new lines,
so if having the whole record on one line is important, set escape-new-line or escapecontrol-characters to true. D efault: fal se.
64 3
escap e- co n t ro l- ch aract ers

If true it will escape all control characters (ASCII entries with a decimal value < 32) with the
ASCII code in octal; for example, a new line becomes #0 12. If this is true, it will override
escape-new-line=fal se. D efault: fal se.
escap e- n ew- lin e
If true it will escape all new lines with the ASCII code in octal; for example #0 12. D efault:
fal se.
Man ag emen t In t erf ace Au d it Lo g File H an d ler At t rib u t es R ef eren ce
A file handler specifies the parameters by which audit log records are output to a file. Specifically it
defines the formatter, file name and path for the file.
File H an d ler At t rib u t es
f o rmat t er
The name of a JSON formatter to use to format the log records. D efault: jso n-fo rmatter.
p at h
The path of the audit log file. D efault: aud i t-l o g . l o g .
relat ive- t o
The name of another previously named path, or of one of the standard paths provided by
the system. If relative-to is provided, the value of the path attribute is treated as relative
to the path specified by this attribute. D efault: jbo ss. server. d ata. d i r.
f ailu reco u n t
The number of logging failures since the handler was initialized. D efault: 0.
max- f ailu reco u n t
The maximum number of logging failures before disabling this handler. D efault: 10.
d isab led - d u e- t o - f ailu re
Takes the value true if this handler was disabled due to logging failures. D efault: fal se.
Man ag emen t In t erf ace Syslo g H an d ler At t rib u t es R ef eren ce
A syslog handler specifies the parameters by which audit log entries are sent to a syslog server,
specifically the syslog server's hostname and the port on which the syslog server is listening.
Sending audit logging to a syslog server provides more security options than logging to a local file
or local syslog server. Multiple syslog handlers can be defined and be active at the same time.
Syslog servers vary in their implementation, so not all settings are applicable to all syslog servers.
Testing has been conducted using the rsyslog syslog implementation.
The Syslog Handler Attributes lists only the high-level attributes. Each attribute has configuration
parameters, and some have child configuration parameters. To detail of a syslog handler's
attributes, run the following command.
64 4
Appendix A. Supplement al References
/core-service=management/access=audit/syslog-handler=mysyslog:readresource-description(recursive=true)
Syslo g H an d ler At t rib u t es
ap p - n ame
The application name to add to the syslog records as defined in section 6.2.5 of RFC-5424.
If not specified it will default to the name of the product.
d isab led - d u e- t o - f ailu re
Takes the value true if this handler was disabled due to logging failures. D efault: fal se.
f acilit y
The facility to use for syslog logging as defined in section 6.2.1 of RFC-5424, and section
4.1.1 of RFC-3164.
f ailu reco u n t
The number of logging failures since the handler was initialized. D efault: 0 .
f o rmat t er
The name of the formatter to use to format the log records. D efault: jso n-fo rmatter.
max- f ailu reco u n t
The maximum number of logging failures before disabling this handler. D efault: 10 .
max- len g t h
The maximum length of a log message (in bytes), including the header. If undefined, it will
default to 10 24 bytes if the sysl o g -fo rmat is R FC 316 4 , or 20 4 8 bytes if the sysl o g fo rmat is R FC 54 24 .
p ro t o co l
The protocol to use for the syslog handler. Must be one and only one of ud p, tcp or tl s.
reco n n ect - t imeo u t
Available from JBoss EAP 6.4. The number of seconds to wait before attempting to
reconnect to the syslog server, in the event connectivity is lost. D efault: -1 (D isabled).
syslo g - f o rmat
Syslog format: RFC-5424 or RFC-3164. D efault: R FC -54 24 .
t ru n cat e
Whether or not a message, including the header, should be truncated if the length in bytes
is greater than the value of the max-l eng th attribute. If set to fal se messages will be split
and sent with the same header values. D efault: fal se.
Report a bug
64 5
Appendix B. Revision History

R evisio n 6 .4 .0- 4 0
T h u rsd ay O ct o b er 08 2015
N id h i C h au d h ary
Red Hat JBoss Enterprise Application Platform 6.4.0.GA Continuous Release
R evisio n 6 .4 .0- 26
T u esd ay Ap ril 14 2015
Red Hat JBoss Enterprise Application Platform 6.4.0.GA
64 6
Lu cas C o st i

JBoss Enterprise Application Platform-6.4-Administration and Configuration Guide-En-US

Uploaded by

Copyright:

Available Formats

JBoss Enterprise Application Platform-6.4-Administration and Configuration Guide-En-US

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JBoss Enterprise Application Platform-6.4-Administration and Configuration Guide-En-US

Uploaded by

Copyright:

Available Formats

JBoss Enterprise Application

Red Hat Customer Content Services

JBoss Enterprise Application Platform 6.4 Administration and Configuration

For Use with Red Hat JBoss Enterprise Application Platform 6

T able of Cont ent s

2 .4. Co nfig uratio n Files

3 .3. The Manag ement Co ns o le

3 .5. Manag ement CLI O p eratio ns

3 .7. Manag ement Interfac e Aud it Lo g g ing

6 .5. Datas o urc e Sec urity

Administ rat ion and Configurat ion G uide

10 .4. Dep lo y with the HTTP API

10 .6 . Dep lo y with Maven

10 .8 . Define a Cus to m Direc to ry fo r Dep lo yed Co ntent

10 .9 . Dep lo yment Des c rip to r O verrid es

12.3. Lo g g ing Co nfig uratio n in the CLI

12.5. Lo g g ing Pro files

12.6 . Lo g g ing Co nfig uratio n Pro p erties

13.3. Cac he Co ntainers

13.4. Ab o ut Infinis p an Statis tic s

13.6 . Enab le Infinis p an Statis tic s Co llec tio n

13.8 . JG ro up s Tro ub les ho o ting

15.2. Co nfig ure the HTTP Ses s io n Timeo ut

15.3. Servlet/HTTP Co nfig uratio n

T able of Cont ent s

15.5. Sys tem Pro p erties in JBo s s Web

16 .2. O verview o f Hand lers and Hand ler Chains

17.4. Web Server Co nfig uratio n

17.5. Clus tering

17.10 . O rac le NSAPI Co nnec to r

18 .3. Dead Co nnec tio n Detec tio n

18 .5. Pag ing

18 .7. The Client Clas s p ath

18 .10 . Thread Manag ement

18 .11. Mes s ag e G ro up ing

18 .13. JMS Brid g es

18 .15. Ho rnetQ Clus tering

18 .16 . Hig h Availab ility

18 .17. Perfo rmanc e Tuning

19 .3. Trans ac tio n Referenc es

19 .4. O RB Co nfig uratio n

19 .5. JDBC O b jec t Sto re Sup p o rt

2 1.2. Co nfig uring Bean Po o ls

2 1.3. Co nfig uring EJB Thread Po o ls

2 1.4. Co nfig uring Ses s io n Beans

Administ rat ion and Configurat ion G uide

2 1.6 . Co nfig uring the EJB3 Timer Servic e

2 1.8 . Co nfig uring the EJB3 Remo te Invo c atio n Servic e

2 1.9 . Co nfig uring EJB 2.x Entity Beans

2 2.3. Dep lo y a Res o urc e Ad ap ter

2 2.4. Co nfig ure a Dep lo yed Res o urc e Ad ap ter

2 2.5. Res o urc e Ad ap ter Des c rip to r Referenc e

2 2.6 . View Defined Co nnec tio n Statis tic s

2 2.8 . Dep lo y the Web Sp here MQ Res o urc e Ad ap ter

2 2.9 . Ins tall JBo s s Ac tive MQ Res o urc e Ad ap ter

2 3.3. Mo nito ring

2 4.2. Dep lo ying JBo s s EAP 6 o n Amaz o n EC2

2 4.4. No n-c lus tered Ins tanc es

2 4.5. No n-c lus tered Manag ed Do mains

2 4.6 . Clus tered JBo s s EAP 6