Quick Start Guide

Version 1.2.0.GA This document is intended to provide a reference to quickly et you started !ith the ne!ly released "#ossAS Administration $onsole alon !ith a %asic overvie! of the features it provides to assist !ith the mana ement of your "#oss Application Server & installation.

Overview
This first release of the "#ossAS Administration $onsole 'referred to as $onsole in later references throu hout this Guide( provides the follo!in administrative features)

$onfi uration *nformation a%out the System the "#oss Application Server is runnin on +eploy, -ndeploy, and -pdate .nterprise Applications includin )

.nterprise Applications '.A/s( 0e% Applications '0A/s( /esource Adapters'/A/s( ."# "A/s '."#2 and ."#1(

2ersistent confi uration chan es for the follo!in resources) +ata Sources $onnection 3actories "4S Queues and Topics %ased on "#oss 4essa in $ontrol 5perations Stop, Start, /estart Applications Vie! /esource Statistics Vie! /esource 4etric *nformation

3or related community pro6ect information for the $onsole and "#oss Application Server &, see the references section at the end of this document. 7et8s et started . . .

Installation
+o!nload "#oss Application Server &.1.0.GA from the "#oss AS community do!nload pa e) http)99!!!.6%oss.or 96%ossas9do!nloads9 $lick on the +o!nload link and select the platform:independent ;ip distri%ution for the "+< you8ll %e usin ) "avaS. & = jboss-5.1.0.GA.zip "avaS. > = jboss-5.1.0.GA-jdk6.zip /efer to the "#oss AS &.1.0.GA and "#ossAS Administration $onsole /elease ?otes for specific information on these pro6ect releases. 5nce the do!nload has completed, un;ip it to an installation directory of your choice. 0e !ill refer to "#5SS@A54. as Binstallation:dirC96%oss:&.1.0.GA The $onsole is distri%uted as part of the 'default' and 'all' server confi urations. Start the "#oss AS & server) $JBOSS_HOME/bin and eDecute the command ./run.sh for -niD systems or run.bat for 0indo!s systems The a%ove command starts the 'default' confi uration. *f you prefer to run !ith an alternate confi uration, repeat the a%ove command passin in your confi uration usin the :c option. #elo! is the syntaD for startin the server !ith the 'all' confi uration. .Dample) ./run.sh -c all or run.bat -c all *n addition to the 'default' and 'all' confi urations, the $onsole has %een tested !ith the 'standard' confi uration !hich is also a confi uration provided !ith this distri%ution. To use the $onsole !ith the 'standard' confi , you can copy the admin:console.!ar directory from the 'default' server confi uration as sho!n %elo!. cd $JBOSS_HOME/server/default/deploy cp -pr admin-console.war $JBOSS_HOME/server/standard/deploy 2

*t is eDpected that that $onsole !ill !ork !ith any custom confi uration. -se the a%ove command replacin 'standard' !ith the custom confi uration name of your choice. *f you happen to encounter issues, please file an .4#"52/ "*/A to alert us of the pro%lem. *NOTE: JBoss AS Administration Console is not supported with the 'minimal' or 'web' confi urations pro!ided with the distribution nor confi urations based on those"

Accessing the Console

5nce the server is started, the $onsole is ready to assist you !ith your Application Server administration tasks. Simply point your %ro!ser to) http)99localhost)E0E09admin:console *NOTE: The Console has been tested with #o$illa %ire%o& ' and (nternet E&plorer )" This !ill %rin you to the "#oss AS Administration $onsole 7o in pa e.

7o in credentials are the same as used for the "4F console. A default user is provided for out:of:%oD access. 0hen prompted, enter admin for -sername and 2ass!ord . $lick the Login %utton.

*NOTE: To chan e the default lo in or to add additional users* !isit the +ed ,at -nowled e Base to find out .,ow to enable authentication on JBoss ser!ices such as rmi/http* 0m&/console* and web/ console12" The $onsole provides a sin le administration point for mana in and modifyin your Applications and System /esources. Add, -pdate, 4odify, and +elete functions are availa%le for all resource types. $ontrol 5perations, /esource 4etrics, and $onfi uration modifications are availa%le dependin on the the resource type.

Navigation Overview
5nce successfully lo ed in you have an overall Summary of the "#oss AS & server runnin . The left navi ation pane allo!s direct access to any administrative task. ?ote that these tasks are availa%le for the "#oss AS & server confi uration currently runnin as sho!n in the parenthesis. 5nly one runnin server is mana ed at a time.

$lick on the "#oss AS & 'confi ( link and an overvie! of the system that the "#oss server is runnin on such as 5peratin System information and host name is sho!n.

All applications and resources discovered durin server start up are availa%le. The screen shot %elo! is sho!n !ith all the vie!s eDpanded. *f your vie! is not consistent !ith the teDt in this document %ein referenced, %e sure that the vie! is eDpanded %y clickin on the arro! neDt to the item %ein referenced.

&

Applications Overview
All applications discovered !hen the server !as started are listed in the Summary vie!. Ao!ever, Applications can %e listed %y their Types to simplify the vie!. The Applications Types that can %e mana ed in this release are)

."# 2.D Application '."# "A/(s ."# 1.D Application '."# "A/(s .m%edded ."# 2.D Application '."# "A/(s .m%edded ."# 1.D Application '."# "A/(s .m%edded /esource Adapters '/A/(s .m%edded 0e% Applications '0A/(s .nterprise Applications '.A/(s /esource Adapters '/A/(s 0e% Applications '0A/(s

?ote that the .m%edded application types !ere deployed as part of an .nterprise Archive. They are listed separately for easier mana ement and each em%edded archive sho!s the relationship to its8 parent >

in the Summary ta%. .m%edded applications are mana ed via their parent. *n other !ords, they cannot %e deleted or updated nor do control operations apply. The mana ement of these applications are done via the operations on the parent. Applications are eDpected to %e "ava..:compliant and appropriately packa ed for deployment to the application server includin any specific runtime descriptor information.

Add New Application eso!rce

To add 'deploy( applications, navi ate to the Application type you !ant to add. *n this eDample, !e !ill use an .nterprise Applications. $lickin on the link "nterprise Applications #"A s$

0ill %rin you to the .nterprise Application '.A/( Summary Ta%.

$lickin on

%rin s you to Add New "nterprise Application #"A $ ta%. $lick the % O&'" %utton and select the .ear file to %e deployed. $lick (ON)*N+" to proceed !ith the application deployment. The status of the deployment !ill %e sho!n and if successful, added to the list of applications ready to %e mana ed. 5ther!ise, the reason for the failed deployment !ill %e sho!n. 3ollo! this procedure for other Application Types that you !ant to Add.

(ontrol Operations
$ontrol 5perations are availa%le for all Application Types. 3rom the .nterprise Application Summary Ta%, select the .nterprise Application deployed in the a%ove step. This %rin s you to the Summary Ta% of that deployed application. Select the $ontrol Ta%. The 5perations availa%le for Application Types are)

')A ) starts this .A/ ')O, stops this .A/ "')A ) stops and then restarts this .A/

+pdating Applications
To -pdate the Application $ontent, select the Application that you !ant to -pdate. $lick on the $ontent Ta%. #/50S. to the location of !here the updated Application resides.

*NOTE: The file to be 3pdated must be the same name as the application selected for 3pdate"

-eleting Applications
Applications can %e +eleted %y navi atin to the Applications Summary Ta% or the Application: specific Type 'such as .nterprise Application( Summary Ta% %y simply clickin the -"L")" %utton neDt to the name of the Application you !ant to delete. 5nce the +.7.T. has %een confirmed, the Application !ill %e undeployed from the server and !ill no lon er %e a%le to %e mana ed. Iou can al!ays Add the resource a ain if needed. As noted a%ove, .m%edded Applications !ill not have the +.7.T. option availa%le.

eso!rces Overview
$lick on the /esources link from the left ?avi ation pane)

%rin s you to the /esources landin pa e sho!in the different types of /esources to %e mana ed.

Specifically,

"#oss 0e% Servlet $ontainer $onnectors Virtual Aosts 10

$onnection 3actories ?o TD $onnection 3actories TD $onnection 3actories +atasources 7ocal TD +atasources ?o TD +atasources FA +atasources "4S +estinations Topics Queues

0hether addin ne! resources or modifyin resources already deployed to the runnin server, the $onsole offers easy mana ement of the resource properties avoidin error:prone editin of F47 confi uration files. ?eDt to each edita%le property is a +escription detailin the use of the property, default value if any, and the affect of the property chan e. $onfi uration errors are immediately detected and !ill %e hi hli hted !hen the attemptin to 'A.". At any time durin editin of a resource confi uration, the chan es can %e (AN("Led. +etailed overvie! of the different resource types is provided %elo!.

/%oss &eb eso!rces

(onnectors

ATT2

The ATT2 connector is setup %y default !ith "#oss 0e% and is ready to use. This connector features the lo!est latency and %est overall performance.

A"2

*f inte ration !ith the native !e% server is needed, an A"2 connector !ill provide faster performance than proDied ATT2. The native connectors supported !ith "#oss 0e% in "#oss Application Server &.1.0.GA release are) 11

"< 1.2.D !ith any of the supported servers mod@proDy on Apache ATT2 Server 2.D 'included %y default in Apache ATT2 Server 2.2(, !ith A"2 ena%led

.irt!al 0osts

/efer to the Virtual Aosts article sho!in an eDample confi uration !ith "#oss Application Server &.

(onnection 1actories
Select $onnection 3actories link under /esources to confi ure a "$A resource adapter connection factory. *NOTE: The resource adapter must alread4 be deplo4ed prior to confi urin the connection factor4" (f this has not 4et been done* simpl4 na!i ate to the +esource Adapters 5+A+6s or Enterprise Application 5EA+6s 5for a resource adapter deplo4ed as part of an Enterprise Archi!e6 from Applications as described abo!e" After clickin on the $onnection 3actories link, you !ill %e %rou ht to the $onnection 3actories Summary Ta% !here the eDistin connection factories deployed to the runnin server !ill %e sho!n. The default vie! is All types !here the Type of $onnection 3actories are)

?o TD $onnection 3actories TD $onnection 3actories

Add New (onnection 1actor2

To add a ne! connnection factory , select the $onnection 3actory Type you !ant to add. Select ?o TD $onnection 3actory to confi ure a connection factory that does not participate in "TA transactions. Alternatively, select the TD $onnection 3actory link for connection factories that !ill participate in "TA transactions. After makin your selection, click on the KAdd a new reso!rceL %utton 12

on the ri ht side of your %ro!ser. Iou !ill %e prompted for the template that !ill %e used to create the confi uration. Iour template choices for each connection factory type are)

?o TD $onnection 3actories default '?oTD$onnection 3actory( TD $onnection 3actories 7ocal Transaction 'TD $onnection 3actory( FA Transaction 'TD $onnection 3actory( default 'TD $onnection 3actory(

$lick (ON)*N+". Iou are no! ready to add the confi uration information for the connection factory. /efer to the +escription column for information descri%in the use of each property. $heck the +n'et %oD if the property !ill not %e used. This is not availa%le for every property. At the end of your confi uration session, click 'A." !hich deploys the confi uration information to the server. $lick (AN("L if you decide not to create the ne! resource.

*NOTE: (f a resource was pre!iousl4 deplo4ed and modified !ia the Console* the administration of the resource should continue to be done !ia the Console" The resource modifications are persistent but will not be reflected in the ori inal confi uration file" (n other words* chan es between manual edits to confi uration files and chan es performed !ia the Console are not interchan eable"

(onnection 1actor2 3etrics

The $onsole provides connection information a%out each $onnection 3actory resource deployed. To vie! the $onnection 3actory metrics, select the connection factory that you !ould like to o%tain information a%out from the $onnection 3actories Summary Ta%. *f there are several connection factory confi uration files deployed, customi;e your vie! simply selectin the type of connection factory you !ant to o%tain metrics a%out.

3rom the specific vie!, click on the name of the $onnection 3actory. Select the 4etrics Ta%. 4etrics and Trait information a%out this connection factory is displayed as sho!n %elo!.

?umeric

11

(onnection 1actor2 (ontrol Operations

3rom the $ontrol ta% of any selected $onnection 3actory, you can 3lush the connection pool or o%tain statistics, includin Su% 2ool statistics.

1G

-ataso!rces
Administration tasks for +atasources are the similar to !hat has %een descri%ed for $onnection 3actories. The main difference is in the template selection for confi urin the resources. To add or modify a previously deployed datasource, click on the +atasources link in the left navi ation panel. The +atasources Summary Ta% is displayed sho!in the datasources confi ured in the runnin server confi uration. The default vie! is to list all +atasource Types. The types of +atasources are)

7ocal TD +atasources ?o TD +atasources FA +atasources

Add New -ataso!rce

To add a ne! +atasource, select the +atasource Type you !ant to add. The +atasource types are self: eDplanatory. Select the appropriate +atasource type that you !ant to add. After makin your selection, click on the KAdd a new reso!rceL %utton on the ri ht side of your %ro!ser. Iou !ill %e prompted for the template that !ill %e used to create the confi uration. Iour template choices for datasource types are) 7ocal TD +atasource 5racle 7ocal TF '7ocal TD +atasource( default '7ocal TD +atasource( ?o TD +atasources 5racle ?o TF '?o TD +atasource( default '?o TD +atasource( FA +atasources 5racle FA 'FA +atasource( 1&

default 'FA +atasource(

After selectin the appropriate template, $lick (ON)*N+". Add the appropriate confi uration information for the datasource. /efer to the +escription column for information descri%in the use of each property. $heck the +n'et %oD if the property !ill not %e used. At the end of your confi uration session, click 'A." !hich deploys the confi uration information to the server. $lick (AN("L if you decide not to create the ne! resource.

*f additional modifications to the resources are needed after they are created, simply click on the /esource to %e modified. $lick on the $onfi uration Ta% !here edits to the confi uration properties can %e made.

4etric information a%out the +atasource is availa%le from the 4etrics Ta% for the selected +atasource. Additionally, $ontrol 5perations that are availa%le for $onnection 3actories are also availa%le for all +atasource types.

1>

/3' -estinations
"4S +estination resources are also mana ea%le via the $onsole. The "4S +estination types are)

Queue Topic

Add New 4!e!e or )opic

To add a ne! "4S +estination resource, select Queue or Topic link under "4S +estinations in the left navi ation panel. $lick on the KAdd a new reso!rceL %utton on the ri ht side of your %ro!ser. The only template option is the default template of the destination type. Select the default template and click (ON)*N+" to proceed !ith confi urin your resource. /efer to the +escription column to assist !ith your confi uration entries and the affect each property modifcation has. *f there are default values for the properties, they !ill %e listed as !ell. 1H

Throu hput and utili;ation 4etric information are availa%le from the 4etrics Ta% for the selected "4S +estination.

(ontrol Operations
$ontrol 5perations are availa%le for "4S +estination. 3rom the "4S +estination Summary Ta%, select the "4S destination to control. This %rin s you to the Summary Ta% of the topic or queue. Select the $ontrol Ta%. The 5perations availa%le for topics and queues are)

"3O." All 3essages /emove all messa es from the destination. ')A ) Start the +estination ')O, Stop the +estination List All 3essages 7ist all messa es for the specified su%scription !ith the specified selecto List -!rable 3essages 7ist all dura%le messa es for the specified su%scription !ith the specified selector List Non -!rable 3essages 7ist all non dura%le messa es for the specified su%scription !ith the specified selector

5perations availa%le specific to queues are)

List 3essage (o!nter As 0)3L Get the messa e counter as AT47 List 3essage (o!nter 0istor2 As 0)3L Get t5e 6essage co!nter 5istor2 as 0)3L eset 3essage (o!nter /eset the messa e counter eset 3essasge (o!nter 0istor2 /eset the messa e counter history

5perations availa%le specific to topics are)

1E

List All '!bscriptions /eturn all su%scriptions for the topic or queue List All '!bscriptions As 0)3L /eturn all su%scriptions for the topic or queue in AT47 List -!rable '!bscriptions /eturn all dura%le su%scriptions for the topic or queue. List -!rable '!bscriptions As 0)3L /eturn all dura%le su%scriptions for the topic or queue in AT47 List Non -!rable '!bscriptions /eturn all non dura%le su%scriptions for the topic or queue List Non -!rable '!bscriptions As 0)3L /eturn all non dura%le su%scriptions for the topic or queue in AT47

5nce the $ontrol operation is eDecuted, the 5peration status is returned and listed in the 5perations Aistory pane.

1J

-eleting eso!rces
Any resource type can %e +eleted %y navi atin to the /esources:specific Type 'e. ., +atasources( Summary Ta% %y simply clickin the -"L")" %utton neDt to the name of the /esource you !ant to delete. 5nce the +.7.T. has %een confirmed, the /esource !ill %e removed from the server and !ill no lon er %e a%le to %e mana ed. Iou can al!ays Add the resource a ain if needed.

e7erences The "#oss AS Administration $onsole distri%uted as part of the "#oss Application Server & release encompasses several open source community pro6ects. The references %elo! provide additional information on those individual pro6ects. Iour feed%ack is requested and appreciated. -se the respective forums for discussions related to these pro6ects and let us kno! of any issues %y filin in the pro6ect "*/A. .m%edded "52/
"#oss Application Server 2rofile Service S.A4 /ich 3aces *f you are runnin "#oss AS G.2.D release, you can do!nload the .m%edded "52/ 1.1.0.GA release to try it out. 20

'!66ar2
This is the first GA release of the "#oss AS Administration $onsole for "#oss AS & %ut the !ork continues to provide our development community ease:of:administration and mana ement capa%ilities.

Abo!t t5e A!t5or Shelly 4cGo!an is a mem%er of the "#oss AS development team !orkin from the 0estford, 4assachusetts .n ineerin office. Aer !ork on the .4#"52/ pro6ect focused on the test desi n and development strate y usin "S3-nit. The tests are included as part of the .4#"52/ pro6ect. 4ore information on the test desi n can %e seen on the .4#"52/ QA !iki.

21