Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

Administration Console Quick Start Guide

JBoss Enterprise Application Platform Common Criteria Certification 5

for use with JBoss Enterprise Application Platform 5 Common Criteria Certification

Edition 5.1.0

JBoss Operations Network development team

Edited by

Isaac Rooskov

Edited by

Laura Bailey

Abstract

This book is a quick start guide to the Admin Console of JBoss Enterprise Application Platform 5.1.0.

Chapter 1. Overview

This document is intended to provide a reference to get you started with the newly released JBoss Enterprise Application Platform Admin Console along with a overview of the features it provides to assist with the management of your JBoss Enterprise Application Platform 5 installation. The Administration Console provides a single administration point for managing and modifying your Applications and Enterprise Application Platform resources.
This release of the Admin Console provides the following administrative features:
  • Deploy, Undeploy, and Update Enterprise Applications including:
    • Enterprise Applications (EARs)
    • Web Applications (WARs)
    • Resource Adapters(RARs)
    • EJB JARs (EJB2 and EJB3)
  • Persistent configuration changes for the following resources:
    • Datasources
    • Connection Factories
    • Service Binding Manager
    • JMS Queues and Topics based on JBoss Messaging
  • View statistics and carry out operations on many other components:
    • Enterprise Application Platform server examples: version, memory usage, thread count and stop operation
    • Hibernate Session factories
    • JBoss Web vhosts: supported aliases
    • JBoss Web connectors: for example, Maximum Request Time
    • EARs and WARs: for example, Average Response Time and lifecycle operations (start, stop and reload)
  • Monitor all standard JVM metrics and execute operations. For example, garbage collection.

Chapter 2. Installation

Throughout this chapter we will refer to the location of JBOSS_HOME as <installation-dir>/jboss-as
The Administration Console is distributed as part of the default, all, web and production server configurations.
Start the server by opening a command prompt at $JBOSS_HOME/bin and execute the command:
On Unix systems:
./run.sh
On Windows systems:
run.bat
The above command starts the default configuration. If you prefer to run with an alternate configuration, repeat the above command passing in your configuration using the -c option. Below is the syntax for starting the server with the all configuration, for example:
On Unix systems:
./run.sh -c all
On Windows Systems:
run.bat -c all
In addition to the configurations mentioned above, it is expected that the Administration Console will work with any custom configuration that supports the installation of Seam applications, however that support is not guaranteed. To use the Console with a different configuration (for instance, the test configuration), you can copy the admin-console.war directory from the default server configuration as shown below (for Unix systems):
cd $JBOSS_HOME/server/default/deploy
cp -pr admin-console.war $JBOSS_HOME/server/test/deploy

Important

The Administration Console is not supported with the minimal configuration provided with the distribution or any configurations based on the minimal configuration.

Chapter 3. Accessing the Console

Once the server is started, simply point your browser to http://localhost:8080/ and then choose the Admin Console link from the list.

Note

This URL assumes you are accessing the Admin Console from the machine your Enterprise Application Platform instance is running on and your server is listening on the default ports and network interface. If you have changed any of these defaults you will have to alter the URL accordingly.

Note

The Admin Console has been tested against and is supported for use with Mozilla Firefox 2.0, 3.0, 3.5 and 3.6; and Internet Explorer 6 and 7. It may also work in other browsers, but it is only supported in the browsers listed here.
Once the Admin Console has been loaded the login page will be displayed:
Login credentials are the same as used for the JMX console. A default user is provided for immediate access as part of the Enterprise Application Platform. In order to enable this user you need to uncomment the setting in $JBOSS_HOME/server/$PROFILE/conf/props/jmx-console-users.properties so that it contains:
admin=admin
Once the jmx-console-users.properties file has been saved, enter admin for both the username and password in the prompts and then click the Login button. After clicking the Login button, the Admin Console will scan your Enterprise Application Platform instance and detect what is running on it. Once this is complete, you will be shown a screen similar to the one below:

Chapter 4. Securing the Console

If JBoss services need to listen on external IP addresses that may be visible to unauthorized users, it is important that authentication is enabled on the Admin Console. Failure to enable authentication could result in exposing administrative services on the JBoss Enterprise Application Platform instance to malicious users, which could result in Denial of Service (DoS) attacks.
Follow the instructions in this section to secure your Admin Console.

Note

In the instructions that follow, $PROFILE refers to the server profile used by the installation, for example, default, minimal, or any custom server profile created by the administrator. All specified paths are relative to $JBOSS_HOME.

4.1. Enabling authentication

In the following web.xml files:
  • server/$PROFILE/deploy/jmx-console.war/WEB-INF/web.xml
  • server/$PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml
Uncomment the following security-constraint fragment:
<security-constraint>
  <web-resource-collection>
    <web-resource-name>HtmlAdaptor</web-resource-name>
    <description>An example security config that only allows
  users with the
    role JBossAdmin to access the HTML JMX console web application
    </description>
    <url-pattern>/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>JBossAdmin</role-name>
  </auth-constraint>
</security-constraint>
In the following jboss-web.xml files:
  • server/$PROFILE/deploy/jmx-console.war/WEB-INF/jboss-web.xml
  • server/$PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/jboss-web.xml
Ensure that a fragment similar to the following is included:
<jboss-web>
  <!-- Uncomment the security-domain to enable security. You will
     need to edit the htmladaptor login configuration to setup the
     login modules used to authentication users.
  -->
  <security-domain>java:/jaas/jmx-console</security-domain>
</jboss-web>

4.2. Enabling authentication for the http invoker

The server/$PROFILE/deploy/http-invoker.sar/invoker.war/WEB-INF/web.xml or server/$PROFILE/deploy/httpha-invoker.sar/invoker.war/WEB-INF/web.xml file (depending on your server profile) must define a JNDIFactory, EJBInvokerServlet, and JMXInvokerServlet in the security realm. This means that the security-constraint element should be similar to:
<security-constraint>
  <web-resource-collection>
    <web-resource-name>HttpInvokers</web-resource-name>
    <description>An example security config that only allows
  users with the
       role HttpInvoker to access the HTTP invoker servlets
    </description>
    <url-pattern>/restricted/*</url-pattern>
  <url-pattern>/JNDIFactory/*</url-pattern>
  <url-pattern>/EJBInvokerServlet/*</url-pattern>
  <url-pattern>/JMXInvokerServlet/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>HttpInvoker</role-name>
  </auth-constraint>
</security-constraint>
This file should also define an associated security domain:
<jboss-web>
  <security-domain>java:/jaas/jmx-console</security-domain>
</jboss-web>
Binding the jmx-invoker to localhost is highly recommended.
To do so, edit server/$PROFILE/conf/jboss-service.xml such that the ServerAddress of the RMI/JRMP invoker is localhost, as shown in the following code snippet:
<!-- RMI/JRMP invoker -->
<mbean code="org.jboss.invocation.jrmp.server.JRMPInvoker"
  name="jboss:service=invoker,type=jrmp">
  <attribute name="RMIObjectPort">4444</attribute>
  <attribute name="ServerAddress">localhost</attribute>
  ....
Add the following lines to the server section of server/$PROFILE/deploy/jmx-invoker-service.xml:
<!-- A pooled invoker bound to localhost -->
  <mbean code="org.jboss.invocation.pooled.server.PooledInvoker"
    name="jboss:service=invoker,type=pooled,host=localhost">
    <attribute name="NumAcceptThreads">1</attribute>
    <attribute name="MaxPoolSize">300</attribute>
    <attribute name="ClientMaxPoolSize">300</attribute>
    <attribute name="SocketTimeout">60000</attribute>
    <attribute name="ServerBindAddress">localhost</attribute>
    <attribute name="ServerBindPort">4443</attribute>
    <attribute
    name="ClientConnectAddress">localhost</attribute>
    <attribute name="ClientConnectPort">0</attribute>
    <attribute name="ClientRetryCount">1</attribute>
    <attribute name="EnableTcpNoDelay">false</attribute>
    <depends
    optional-attribute-name="TransactionManagerService">jboss:service=TransactionManager</depends>
In the <mbean code="org.jboss.invocation.jrmp.server.JRMPProxyFactory" section, change <depends optional-attribute-name="InvokerName"> to:
<depends optional-attribute-name="InvokerName">
    jboss:service=invoker,type=pooled,host=localhost
  </depends>

4.3. Setting up users and roles

In Chapter 3, Accessing the Console, you set up the default user/password combination of admin/admin. Change and update the usernames and passwords for the configured security doman by editing the corresponding credential files:
  • server/$PROFILE/conf/props/jmx-console-users.properties
  • server/$PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/web-console-users.properties
You can change/update roles for the configured security domains by editing the appropriate credential file:
  • server/$PROFILE/conf/props/jmx-console-roles.properties
  • server/$PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/web-console-roles.properties

Chapter 5. User Interface Overview

Once successfully logged in, you have an overall summary of the system that the JBoss Enterprise Application Platform is running on, such as Operating System information and host name.
The Administration Console pages are split up into two main areas:
  • The left navigation panel (blue background) allows the user to browse the different resources which are deployed into their Enterprise Application Platform instance. A tree metaphor is used to represent the resource hierarchy, with the root being the machine the Enterprise Application Platform instance is running on. The tree can be expanded to show child resources, for example the Enterprise Application Platform instance and then within that a list of Datasources.
  • The main resource panel (white background) shows information about a particular resource or resources which were selected from the navigation on the left. This is also the place that allows direct access to all the administrative tasks for a resource (for example, update its configuration), delete it. The resource showing in the main pane is normally highlighted in bold in the navigation pane.

Note

The currently running JBoss Enterprise Application Platform instance, with its configuration shown in parentheses, is found under the JBossAS Servers folder near the top of the navigation tree. Only one running server is managed at a time through the Administration Console. Click on the JBoss Enterprise Application Platform 5 (default) link and an overview of the Enterprise Application Platform instance which is running the Administration Console is shown.

Chapter 6. Resource Panel

You can see in the example above the main tabs which are present for all individual resources. Not all tabs are available for every sort of resource, though Summary and Metrics tabs will always be enabled. If a feature is not supported for a particular resource then that tab is greyed out (for example, the Administration Console does not support configuring a JBoss Web Virtual Host so the Configuration tab for those sort of resources will be disabled). The following is a breakdown of the functionality behind each tab:
  • Summary: This presents a quick overview of the resource including relevant metrics on how it is operating.
  • Configuration: If enabled this tab lets you update the configuration of a resource (for example, increase the pool size for a Datasource) or switch the Enterprise Application Platform instance to use a different set of ports.
  • Metrics: Shows the same information as the summary tab plus any more detailed metrics which are collected on the resource. Metrics will be gathered each time you visit the page.
  • Control: If enabled, this tab lets you execute operations on the resource (for example, stopping the Enterprise Application Platform instance).
  • Content: If enabled this tab lets you update the actual files used to deploy the resource (for example, update the WAR file used to deploy a web application).

Note

The currently selected tab is shown in white, available tabs are blue and unavailable ones are grey.

Chapter 7. Navigation Panel

All applications and resources discovered during server start up should be available underneath the Enterprise Application Platform instance in the navigation tree. The screen shot below is shown with all the items in the tree expanded.

Note

The navigation panel is currently fixed width so to see wider entries use the scroll bar at the bottom of the panel.
The are two sorts of items shown in the navigation panel:
  • Collection of resources: These items are indicated by a yellow folder icon.
  • Individual resources: These are indicated by a blue document icon.
Clicking on a collection resource (for example, the Resources link above) will render in the main panel either:
  • a list of resource categories from where you can drill down further:
  • or a list of actual resources from where you can drill down to see a particular resource. For some resource types you can create or delete instances of a resource from this view.
Expanding one of the folder nodes in the navigation will show either individual resources or further collections of resources which themselves can be expanded.
Click on an individual resource will show the Summary tab for that resource, as seen previously for the Enterprise Application Platform instance. If available, expanding an individual resource node in the navigation will show the child resources it has deployed within it.

Chapter 8. Common Tasks

Next we will give an overview of some common tasks you can do with the Administration Console. Each task will be used to highlight a particular function within the console.
For a detailed list of all the supported resources and the functions the Administration Console can perform on them please see the accompanying resource specific documentation.

Application Deployment

All applications running in the Enterprise Application Platform instance are listed in the summary view under : <machine> : JBossAS Servers : JBoss Enterprise Application Platform 5 (default) : Applications in the navigation. Applications can also further organized by their types to simplify the view:

Important

The Embedded application types were deployed as part of an Enterprise Archive. They are listed separately for easier management and each embedded archive shows the relationship to its' parent. Embedded applications are managed via their parent. In other words, they cannot be deleted or updated and control operations do not apply to them. The management of these applications is done through the operations on the parent.
To deploy an application, navigate to the Application type you want to add. In this example, we will use an Enterprise Application. Clicking on the link Enterprise Applications (EAR)s will bring you to the Enterprise Application (EAR) Summary Tab.
Clicking on:
brings you to Add New Enterprise Application (EAR) page. Click the BROWSE button and select the EAR file to be deployed. Select whether to deploy the app exploded or to the farm directory. Click CONTINUE to proceed with the application deployment. The status of the deployment will be shown and if successful, added to the list of applications ready to be managed. Otherwise, the reason for the failed deployment will be shown.
You can follow this same procedure for other application types that you want to add.

Chapter 9. Updating Applications

To update an application, select it from the navigation panel and then in the main panel click on the Content Tab. BROWSE to the location of where the updated application resides then hit the UPDATE button. Example below of updating an .EAR deployment:

Important

The file to be updated must have the same name as the application you wish to update.

Chapter 10. Application undeployment and resource removal

Many types of resources including applications can be deleted by navigating to the Resources' Type specific (for example, Enterprise Application (EAR)s) Summary Tab and simply clicking the DELETE button next to the name of the resource you want to delete. For example, to undeploy an EAR file, choose the Enterprise Application (EAR)s folder from the navigation and then in the main panel find the application you are looking to remove and click the DELETE button next to it. Once the removal has been confirmed, the Application will be undeployed from the server and will no longer be able to be managed. You will have to deploy it again if it is needed. As noted above, Embedded Applications do not have the delete option available.

Chapter 11. Adding Resources

Other resources, in addition to applications, can be added to your Enterprise Application Platform instance using the Administration Console. In fact whether you adding new resources or modifying resources already deployed to the running server, the Administration Console offers easy management of the resource properties avoiding error-prone editing of XML configuration files.
Similar to deploying an application, choose the specific type of resource you want to add from the navigation panel (for example, Local Tx Datasources rather than just Datasources), this will bring up the Summary tab for this type. Next hit the Add a new resource button on the right hand side of the main panel. You will be prompted for the template that will be used to create the configuration.
A template is just a set of suggested values to use for the properties defined on that resource. For example, the Oracle templates contain suggested values that are typically used when creating a Datasource for connecting to an Oracle database. Your template choices for datasource types are:
  • Local Tx Datasource
    • Oracle Local TX (Local Tx Datasource)
    • default (Local Tx Datasource)
  • No Tx Datasources
    • Oracle No TX (No Tx Datasource)
    • default (No Tx Datasource)
  • XA Datasources
    • Oracle XA (XA Datasource)
    • default (XA Datasource)
After selecting the appropriate template, click CONTINUE. Add the appropriate configuration information for the datasource. Next to each editable property is a description detailing the use of the property, default value if any, and the affect of the property change. Common configuration errors are detected and will be highlighted after attempting to save. Check the Unset box if the property will not be used. At the end of your configuration session, click SAVE at the bottom of the page which deploys the configuration information to the server. Click CANCEL if you decide not to create the new resource.
After you have saved the new configuration the main panel should return to displaying a list of resources along with a message about whether or not the resource creation succeeded.

Important

Any database drivers needed for the Datasource to function correctly must be deployed to the Enterprise Application Platform instance separately.
A similar procedure works for creating JMS Destinations and Connection Factories. For Connection Factories however the required resource adapter must already be deployed prior to configuring the connection factory. If this has not yet been done, simply navigate to the Resource Adapters (RAR)s or Enterprise Application (EAR)s (for a resource adapter deployed as part of an Enterprise Archive) and deploy the adaptor JAR file.

Chapter 12. Updating Resource Configurations

For resources that support configuration, either created through the Administration Console or deployed separately, you can use the Console to make modifications to their settings. Simply choose the resource to be modified from the navigation panel or from one of the resource list views and then select its Configuration tab, from where changes can then be made:
Updating a resources configuration follows a very similar pattern to adding a resource described above. Change the properties you want to be updated and hit the SAVE button at the bottom of the page and the changes will be applied to the Enterprise Application Platform instance.

Warning

If a resource was previously deployed and modified via the Console, the administration of the resource should continue to be done via the Console. The resource modifications are persistent but will not be reflected in the resources original configuration file. This means that changes between manual edits to configuration files and changes performed via the Console are not interchangeable. If you make a change to a configuration file outside of the Administration Console it will override and replace any changes you have previously made via the Console.

Chapter 13. Monitoring the Enterprise Application Platform Instance

Basic information is provided on every resource managed by the Admin Console via the resources Summary tab. However some resources such as the Enterprise Application Platform instance itself , also offer more detailed metrics. See below for an example:
This metrics are collected from the resource when the Metrics tab is viewed and can be recalculated by hitting the REFRESH button at the bottom main panel.

Note

In order to see JVM resources and metrics, the Enterprise Application Platform instance must be started with the -Djboss.platform.mbeanserver system property specified as part of JAVA_OPTS.

Chapter 14. Flushing the Connection Pool for a Datasource

Certain resources, such as Datasources, have support for executing particular operations from the Administration Console. These operations are exposed on the Control tab for a particular resource. Below is the Control tab for a Datasource:
In order to flush the connection pool associated with a Datasource you navigate to the Datasource you are interested in, select its Control tab and then push the FLUSH button. Once the Control operation is executed, the Operation status is returned and listed in the Operations History section at the bottom of the main pane. Multiple operations can be executed and a history of results is maintained until the Enterprise Application Platform instance is restarted.
Other control operations include stopping the Enterprise Application Platform instance and removing all messages from a JMS Queue.

Note

Starting the Enterprise Application Platform from the Administration Console is not supported because the Console requires a running instance of the Enterprise Application Platform in order to operate.

Chapter 15. Port Configuration

The Service Binding Manager co-ordinates which ports the Enterprise Application Platform instance listens on when it starts up and the Administration Console provides a mechanism for configuring this service to change which ports get used. In the navigation pane select the SBM: <machine> : JBossAS Servers : JBoss Enterprise Application Platform 5 (default) : Service Binding Manager. Next go to its Configuration tab and for the Active Binding Set Name property enter the name of the new port set you wish the Enterprise Application Platform instance to use and hit the SAVE button at the bottom of the page. Out of the box, the Enterprise Application Platform ships with four port sets defined as:
  • ports-default: The standard ports, for instance JBoss Web listens for HTTP requests on 8080. You can view all of the standard port settings on the Configuration tab of the Service Binding Manager resource.
  • ports-01: The standard ports incremented by 100. For example, HTTP is on 8180
  • ports-02: The standard ports incremented by 200. For example, HTTP is on 8280
  • ports-03: The standard ports incremented by 300. For example, HTTP is on 8380
If you wish to specify a different range of ports to use then you can create your own Service Binding Set resource through the Administration Console. Select the Service Binding Sets folder from the navigation, hit the Add a new resource button on the main panel and enter in the necessary information.
Once you have updated the configuration for the Service Binding Manager, the Enterprise Application Platform instance must be restarted for those changes to take effect. After the restart, the new ports will be used when accessing the Administration Console (for example, http://localhost:8180/admin-console).

Appendix A. Revision History

Revision History
Revision 5.1.0-111.4002013-10-31Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 5.1.0-1112012-07-18Anthony Towns
Rebuild for Publican 3.0
Revision 5.1-0Tue Aug 03 2010Rebecca Newton
Changed version number in line with new versioning requirements.
Revised for JBoss Enterprise Application Platform 5.1.0.GA, including:
JBPAPP-3278
JBPAPP-3276
JBPAPP-4776
Revision 1.0-0Tue Feb 09 2010Laura Bailey
Initial draft.

Legal Notice

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