Managing JBoss Servers with JBoss ON

JBoss Operations Network 3.0

real scenarios for managing EAP instances

December 7, 2011

Abstract

Once JBoss Operations Network is installed, you are ready to set up your inventory. The inventory in JBoss ON lists all of the recognized platforms, servers, and services

1. Managing JBoss Products with JBoss ON

JBoss Operations Network provides extra tools that help manage JBoss server instances. These management tools cover everything from manually configuring a JBoss inventory to applying JBoss patches.

2. Deploying Applications on JBoss Instances

A number of different types of services can be deployed on a JBoss instance by adding it as a child of that instance. JBoss ON provides additional guidance and options in the UI to simplify the process for deploying EARs, WARs, data sources, connection factories, and JMS queues.

2.1. Deploying EAR and WAR Files

  1. Search for the JBoss server instance to which to deploy the EAR or WAR.
  2. On the details page for the selected JBoss server instance, open the Inventory tab.
  3. In the Create New drop-down menu, select the item for - Web Application (WAR) or - Enterprise Application (EAR), as appropriate.
  4. In the resource form, enter the information for the application to be deployed. Aside from the obvious settings, like the resource name, the WAR or EAR resource entry requires the following information:
    • The package name that the EAR or WAR file will be deployed as. In other words, the target entry name.
    • The package architecture.

      Note

      For EAR and WAR deployment, the package architecture should always be noarch.
    • The full path to the file to be deployed, in the File field.
    • Whether the file should be unzipped when it is deployed.
    • The path to the directory to which to deploy the EAR or WAR package. The destination directory is relative to the JBoss server instance installation directory; this cannot contain an absolute path or go up a parent directory.

2.2. Deploying Data Sources

  1. Search for the JBoss server instance to which to deploy the data source.
  2. On the details page for the selected JBoss server instance, open the Inventory tab.
  3. In the Create New drop-down menu, select the item for - Data Sources.
  4. Select a template for the data source. There are three data sources templates to populate a data source with common information:
    • The default template is used with SQL databases like PostgreSQL or MySQL
    • The Oracle Local TX is used for Oracle databases with local transactions.
    • The Oracle XA template is used for Oracle databases with XA transactions.
  5. Along with the obvious settings, like the resource name, enter the information for the specific child resource to be deployed:
    • The type of data source to create, either No TX Data Sources, Local TX Data Sources or XA Data Sources
    • A unique JNDI name for the DataSource wrapper to use to bind under
    • The fully qualified name of the JDBC driver or DataSource class, such as org.postgresql.Driver
    • The JDBC driver connection URL string, such as jdbc:postgresql://127.0.0.1:5432/foo
    • The username and password to use to connect to the data source
    • The minimum and maximum connection pool sizes for this data source
    Additional settings are available under the Advanced Settings area. These are the same as the advanced settings available when the JBoss ON server is installed.

2.3. Deploying Connection Factories

  1. Search for the JBoss server instance to which to deploy the connection factory.
  2. On the details page for the selected JBoss server instance, open the Inventory tab.
  3. In the Create New drop-down menu, select the item for - Connection Factory.
  4. Along with the obvious settings, like the resource name, enter the information for the specific child resource to be deployed:
    • The type of connection factory to create, either tx-connection-factory (transaction) or no-tx-connection-factory (no transaction)
    • A unique JNDI name for the DataSource wrapper to use to bind under
    • The username and password to use to connect to the data source
    • The minimum and maximum connection pool sizes for this data source
    Additional settings are available under the Advanced Settings area. These are the same as the advanced settings available when the JBoss ON server is installed.

2.4. Configuring JMS Queues and Topics

JMS Queues and JMS Topics are child resources of a JBossMQ service or JBossMessaging service resource, which itself is a child of a JBoss server instance.
  1. Search for the JBoss messaging service to which to deploy the JMS queue or topic.
  2. On the details page for the selected JBoss messaging service, open the Inventory tab.
  3. In the Create New drop-down menu, select the item for - JMQ JMS Topic or - JMQ JMS Queue, as appropriate.
  4. Aside from the obvious settings, like the resource name, the JMS Queue or JMS Topic entry requires two additional parameters:
    • The name of the queue or topic to use as the JMX object name
    • A unique JNDI name for the DataSource wrapper to use to bind under
    Additional settings are available under the Advanced Settings area. These are the same as the advanced settings available when the JBoss ON server is installed.

2.5. Updating and Deleting Applications on JBoss Servers

EARs and WARs can both be updated on JBoss server instances simply by uploading the updated packages.
  1. Browse to the EAR or WAR resource in the JBoss ON UI.
  2. In the EAR or WAR resource details page, open the Content tab, and click the New subtab.
  3. Click the UPLOAD NEW PACKAGE button.
  4. Click the UPLOAD FILE button.
  5. In the pop-up window, click the Add button, and browse the local filesystem to the updated WAR or EAR file to be uploaded.
  6. Click the UPLOAD button to load the file and dismiss the window.
  7. In the main form, select the repository where the WAR or EAR file package should be stored. If one exists, select an existing repository or a subscribed repository for the resource. Otherwise, create a new repository.
  8. Confirm the details for the new package, then click CONTINUE.
When the package is successfully uploaded, the UI redirects to the history page on the Content tab.
Deployment History for a Resource

Figure 1. Deployment History for a Resource

Note

To undeploy an EAR or WAR, simply delete the EAR or WAR child resource.

3. Applying JBoss Patches

Content management can be used to apply cumulative patches to JBoss Enterprise Application Platform 4. By default, the JBoss ON server comes pre-configured with the JBoss Patch Content Source and JBoss Patch Repository.
A content source connects a JBoss ON server to all the JBoss patches. A repository maps a content source to the resources in the inventory that the patches are applied to. For JBoss patches, the default content provider connects the JBoss ON server to the cumulative patches provided by the JBoss Customer Service Portal. The default repository associated with the content provider is where the metadata about the patches and the patches themselves are stored within JBoss ON.
The patch process updates existing JAR and class files with upgraded JAR and class files that are contained in the patch package. Other changes that need to be completed manually (all the "Not Performed" steps, for example) are also listed. If the configuration does not include one of the JAR files to be patched, then that step is skipped.
The patching process does not care what the server configuration profile is called or which base configuration it is derived from.
The JBoss ON agent is the entity which actually executes the patching process on a resource. The agent is informed of updates, pulls the information from the server, and then updates the local JAR and class files within the managed JBoss instance. The patching process runs independently of any server configuration profile or base configuration.

3.1. Supported JBoss Products for Patch Updates

JBoss Enterprise Application Platform 4 can receive and apply patch updates through the JBoss CSP feed in JBoss ON.

Note

Patch updates using the Patch RSS Feed is not supported for JBoss Enterprise Application Platform 5 or newer.

Note

A CSP feed is only available for a product or a specific version of a product if there is a patch in the CSP for that product. JBoss ON depends on the JBoss CSP to provide patch information.

3.2. Situations That Can Require Manual Steps

Some patches require additional, manual changes, such as editing an XML configuration file. Any required manual changes are listed as special steps in the patch installation summary. There are several different situations that require manual intervention:
  • The file to be patched is not present in the configuration.
  • There are files that need to be removed manually.
  • Configuration files, such as XML or Java properties files, require patches that need to be applied manually.
  • Seam is being used and must be patched manually.

3.3. Enabling the Default JBoss Patch Content Source

Note

Perform patch installations during off hours or scheduled maintenance periods.
  1. In the Administration tab in the top menu, open the Content menu and select the Content Sources item.
  2. Click the JBoss CSP Patch Feed source.
  3. Click the Edit button at the bottom of the CSP Feed Settings area to modify the content source.
  4. Fill in the required connection information.
    Most of the default settings, such as the schedule, can be kept.

    Important

    Keep the Lazy Load checkbox activated, or all patches defined in the RSS feed, 1 GB of data, is preemptively downloaded by the JBoss ON server.
  5. Click Save.
  6. Optionally, use Synchronize button to force the content source to pull down the latest RSS Feed and synchronize it with the local data. The history of synchronization attempts is listed in the Synchronization Results section.

3.4. Subscribing a Specific Resource to the Default JBoss Patch Repository

  1. In the Resources item in the top menu, go to the Servers item.
  2. Search for the JBoss instance to subscribe to the repository.
  3. On the JBoss server resource's entry page, open the Content tab and select the Subscriptions subtab. The JBoss patches repository is listed as available for subscription.
  4. Select the checkbox beside the JBoss patches repository, and click the SUBSCRIBE button. When the assignment is complete, the repository is listed under the Current Resource Subscriptions area, rather than Available Repositories.

3.5. Subscribing Multiple JBoss Resources to the Default JBoss Patch Repository

The repository is associated with a content source (the patches that can be applied) and resources are then subscribed to this repository (where the patches can be applied to).
  1. In the Administration tab in the top menu, open the Content menu and select the Repositories item.
  2. Click the JBoss Patch Channel.
    The JBoss patch repository is associated with the JBoss patch content source by default. To associate the repository to another content source, click the ASSOCIATE... button and assign the content source.
  3. In the main page for the repository, click the SUBSCRIBE... button to subscribe JBoss resources to the patch repository.
  4. In the search area, select Server in the drop-down menu.
  5. Select all the JBoss server instance resources to subscribe to this repository.

3.6. Applying a Patch

For patches to be applied to a JBoss server, the server must first be subscribed to the JBoss content repository.
  1. Stop the JBoss instance.
  2. In the Resources item in the top menu, go to the Servers item.
  3. Search for the JBoss instance to patch.
  4. On the JBoss server resource's entry page, open the Content tab and select the New subtab. This lists all of the packages and patches which are available for that specific resource type.
  5. Select the checkboxes beside the names of the patched to install, and click the DEPLOY SELECTED button.
  6. Review the information on the page and verify everything is correct. Click the VIEW link in the Instructions column to review the steps that will be performed during the package installation process.
  7. Optionally, enter any notes to describe the patch deployment or environment.
  8. Click the CONTINUE button to install the updates. The patch process runs in the background; the progress can be viewed in the History subtab of the Content tab.
  9. When the installation process is complete, the patch job is listed in the Completed Requests area. Clicking the VIEW button displays the list of steps that performed in the process and whether they succeeded, failed, or were skipped.
  10. When the patch process is complete, start the JBoss instance.

4. Managing mod_cluster Deployments

The mod_cluster module provides intelligent, dynamic load balancing for web applications. There are two halves to mod_cluster: one in the JBoss application server (which manages the web application contexts) and one in the HTTP server (which manages sessions and routing). JBoss ON monitors and manages the mod_cluster module within the JBoss server.

Note

JBoss ON supports mod_cluster version 1.1.2. This version of mod_cluster is not currently supported on JBoss EAP or the httpd service on Red Hat Enterprise Linux.

4.1. About mod_cluster

mod_cluster is an HTTP load balancer that provides a level of intelligence and control over web applications that is not available with other HTTP load balancers. mod_cluster has lots of features that improve performance and management, but two are crucial:
  • By using multicast (advertising), mod_cluster signals workers what proxy servers are available, so workers can register themselves dynamically with the cluster domain.
  • Using a special communication layer between the JBoss server and the HTTP server, mod_cluster can not only register when a web context is enabled but also when it is disabled and removed from load balancing. This allows mod_cluster to handle full web application life cycles.
More detail about the features of mod_cluster is in the product documentation at http://www.jboss.org/mod_cluster.
mod_cluster has two modules: one for the HTTP server which handles routing and load balancing and one for the JBoss server to manage the web application contexts. Both modules must be installed and configured for the cluster to function.
The mod_cluster Topology

Figure 2. The mod_cluster Topology

In JBoss ON, the entire mod_cluster domain is imported as a child resource for the JBoss server. The web application contexts are listed as children resources for the cluster, with contexts as children within the mod_cluster module.
The mod_cluster Resource Hierarchy

Figure 3. The mod_cluster Resource Hierarchy

Important

The mod_cluster module in the HTTP server is configured externally from JBoss ON and is not managed by JBoss ON.
The mod_cluster module in the JBoss server can be managed by JBoss ON, and it is critical that the cluster is properly configured in order for JBoss ON to manage its resources. JBoss ON detects mod_cluster like any other JMX resource (such as Hibernate).
There are a number of resources available for installing and configuring mod_cluster:

4.2. Managing mod_cluster

The mod_cluster properties provide direct management over how the mod_cluster domain operates. Almost any part of the mod_cluster configuration can be managed through JBoss ON, but two elements are critical for domain behavior:
  • How the mod_cluster domain handles sticky sessions. Sticky sessions are enabled in mod_cluster by default, but this can be disabled or its behavior can be changed through the configuration properties.
  • Enabling advertising (multicast). mod_cluster can send the JBoss information to any VirtualHost configured in the HTTP server. This allows workers to find the cluster and register themselves with the JBoss server dynamically.
Setting Server-Level Properties

Figure 4. Setting Server-Level Properties

The server-level operations apply to all web application contexts configured within the mod_cluster domain domain. The obvious ones that impact the web application contexts are enabling and disabling all contexts. The other options are used to reset the mod_cluster domain after an error (reset the node) or reload the cluster configuration after making changes to the cluster properties.
Running Server-Level Operations

Figure 5. Running Server-Level Operations

4.3. Managing Web Applications Contexts

JBoss ON manages the full lifecycle of web application contexts within the mod_cluster load-balancing cluster.
Web application contexts can be stopped or disabled. Stopping or disabling a webapp context removes it from load-balancing balancing so that the Apache server cannot forward requests to the webapp, but it leaves the application running and available directly from the JBoss server address. (Stop allows the webapp context to drain before removing it from the load-balancing, so this essentially shuts down the webapp gracefully. It can take several minutes or even hours for the webapp context to stop. Disabling a webapp context immediately removes it from load balancing.)
JBoss ON has operations that allow JBoss administrators to manage the state of their web contexts within the mod_cluster domain.
Running Web Application Context Operations

Figure 6. Running Web Application Context Operations

Web context resource operations only apply to the specific selected context.

5. Document Information

This guide is part of the overall set of guides for users and administrators of JBoss ON. Our goal is clarity, completeness, and ease of use.

5.1. Giving Feedback

If there is any error in this guide or there is any way to improve the documentation, please let us know. Bugs can be filed against the documentation for the community-based RHQ Project in Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as specific as possible, so we can be more effective in correcting any issues:
  1. Select the Other products group.
  2. Select RHQ Project from the list.
  3. Set the component to Documentation.
  4. Set the version number to 3.0.
  5. For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct description of the problem, such as incorrect procedure or typo.
    For enhancements, put in what information needs to be added and why.
  6. Give a clear title for the bug. For example, "Incorrect command example for setup script options" is better than "Bad example".
We appreciate receiving any feedback — requests for new sections, corrections, improvements, enhancements, even new ways of delivering the documentation or new styles of docs. You are welcome to contact Red Hat Content Services directly at docs@redhat.com.

5.2. Document History

Revision History
Revision 3.0-52013-10-31Rüdiger Landmann
Rebuild with publican 4.0.0
Revision 3.0-0December 5, 2011Ella Deon Lackey
With the initial release of JBoss Operations Network 3.0.

Index

J

JBoss
applying patches, Applying JBoss Patches
enabling the default patch content source, Enabling the Default JBoss Patch Content Source
managing and configuring, Managing JBoss Products with JBoss ON
subscribing resources to the default patch, Subscribing Multiple JBoss Resources to the Default JBoss Patch Repository

P

patches
applying, Applying a Patch

R

resources
child
connection factories, Deploying Connection Factories
data sources, Deploying Data Sources
EAR and WAR, Deploying EAR and WAR Files
jms queues and topics, Configuring JMS Queues and Topics
child types, Deploying Applications on JBoss Instances
managing and configuring JBoss products, Managing JBoss Products with JBoss ON

Legal Notice

Copyright © 2011 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.