Skip to end of metadata
Go to start of metadata

Interfaces and ports

Interface declarations

JBoss AS 7 uses named interface references throughout the configuration. A network interface is declared by specifying a logical name and a selection criteria for the physical interface:

This means the server in question declares two interfaces: One is referred to as "management"; the other one "public". The "management" interface is used for all components and services that are required by the management layer (i.e. the HTTP Management Endpoint). The "public" interface binding is used for any application related network communication (i.e. Web, Messaging, etc). There is nothing special about these names; interfaces can be declared with any name. Other sections of the configuration can then reference those interfaces by their logical name, rather than having to include the full details of the interface (which, on servers in a management domain, may vary on different machines).

The domain.xml, host.xml and standalone.xml configuration files all include a section where interfaces can be declared.  If we take a look at the XML declaration it reveals the selection criteria. The criteria is one of two types: either a single element indicating that the interface should be bound to a wildcard address, or a set of one or more characteristics that an interface or address must have in order to be a valid match. The selection criteria in this example are specific IP addresses for each interface:

Some other examples:

Socket Binding Groups

The socket configuration in JBoss AS 7 works similar to the interfaces declarations. Sockets are declared using a logical name, by which they will be referenced throughout the configuration. Socket declarations are grouped under a certain name. This allows you to easily reference a particular socket binding group when configuring server groups for instance (Managed Domain). Socket binding groups reference an interface by it's logical name:

A socket binding includes the following information:

  • name -- logical name of the socket configuration that should be used elsewhere in the configuration
  • port -- base port to which a socket based on this configuration should be bound. (Note that servers can be configured to override this base value by applying an increment or decrement to all port values.)
  • interface (optional) -- logical name (see "Interfaces declarations" above) of the interface to which a socket based on this configuration should be bound. If not defined, the value of the "default-interface" attribute from the enclosing socket binding group will be used.
  • multicast-address (optional) -- if the socket will be used for multicast, the multicast address to use
  • multicast-port (optional) -- if the socket will be used for multicast, the multicast port to use
  • fixed-port (optional, defaults to false) -- if true, declares that the value of port should always be used for the socket and should not be overridden by applying an increment or decrement

Securing the Management Interfaces

In addition to the services made available by the running application server or servers, JBoss AS 7 also makes available two management interfaces to allow remote clients to connect for the purpose of managing the running JBoss AS 7 installation. This page describes how these interfaces are used and how they can be secured.

The two management interfaces that are exposed are a HTTP interface and a Native interface. The HTTP interface is both used to provide the GWT based administration console and also allows for management operations to be executed using a JSON encoded protocol and a de-typed RPC style API.  When running a standalone server the native interface allows for management operations to be executed over a proprietary binary protocol. This is used by the supplied command line interface tool and can also be used by other remote clients that use the jars distributed with JBoss AS 7 to communicate.

When running a managed domain the use of these interfaces is slightly more complicated. On each host there will be a host controller process. On one host the host controller will be configured to act as the master domain controller; on the remaining hosts the host controller will be a slave to the master domain controller.  In a managed domain the HTTP interface is still used in the same way; it allows GWT based administration console to run on the master domain controller and also allows any custom HTTP and JSON based management clients to execute management operations on any host controller. The native interface allows the command line interface tool to execute operations on the domain controller or on any host controller. The native interface however is also used for a couple of additional clients: once the host controller spawns the actual application server instances, these establish a connection back to the host controller through the native interface that it exposes, and, finally, the slave host controllers use the native interface to establish a connection back to the master domain controller to initially obtain a copy of the domain model and then to subsequently receive operations from the master domain controller.

Initial Configuration

The interfaces to be exposed are defined in the standalone.xml configuration for a standalone server and are in the host.xml configuration for a server within a managed domain. In both cases the structure of the configuration is the same.

By default the native interface listens on port 9999 and the http interface listens on port 9990. The management interfaces are also associated with a network interface named 'management'. Although the configuration of this network interface by default matches the configuration of the 'public' interface it is recommended that these two configurations are not combined. Keeping them separate helps ensure that any changes to make the application server services more publicly visible don't inadvertently expose the management interfaces more publicly than is required.

Quick Configuration

The remaining sections in this chapter describe the security realm configuration in more detail - however if you would like to quickly enable a security realm and refine it for your requirements the default configuration contains a pre-defined realm definition based on a properties file and a script that can be executed using the command line interface to enable the security realm.

The security realms are defined within the <management> element of the standalone.xml or host.xml configurations. By default the following realm is defined:

This default realm is used to authenticate the user connecting against a properties file called 'mgmt-users.properties' located in the same folder as the configuration. By default there are no users defined in the properties file so new users will need to be added in the format username=password.

To manually enable this realm the two interfaces can be configured to use this realm.

This will enable HTTP Digest authentication for the HTTP interface and within the Native interface will also enable the Digest SASL mechanism - this means that for authentication the raw passwords are not transmitted from the client to the server.

To use the script to enable the realm first edit the 'mgmt-users.properties' script as the changes will take effect immediately so you will need at least one user defined and then execute one of the following commands.

For standalone server: -

For a server in a managed domain: -

Please do be aware that this script is specifically written to run against a host called master which is the name in the default configuration. If additional hosts with unique names are created either the script should be updated or security manually applied in the new configuration.  Also please note that the script only affects the named host it is run against; if there are multiple host controllers this script should be run against all of them with their correct names.  Also please read the remainder of this chapter for information on how to configure the slave host controller to authenticate when connecting to the master host controller.

Disabling JMX Remote Access

In addition to the above JBoss management protocols, remote JMX connectivity, which allows triggering JDK and application management operations. In order to secure an installation this service needs to be disabled by either removing the remote connector configuration, or removing the entire subsystem.

Detailed Configuration

The configuration of the management interfaces happens within three elements inside the parent <management> element.

  • <security-realms /> - This is where one or more security realms can be configured to define how remote users connecting to this server will be authenticated and also to define the identity of the server.
  • <outbound-connections /> - Sometimes the configuration of the security realms will require a connection to an external resource; these connections are defined here.
  • <management-interfaces /> - This is where the HTTP interface and Native interfaces are defined as covered in the introduction.

Management Interfaces

The security configuration for the individual management interfaces is the simplest. All that is required for the interfaces is a 'security-realm' attribute with the name of the security realm to use. As the management interface starts it will query the capabilities of the security realm and enable the transport level security accordingly; e.g. the HTTP interface will attempt to use Digest authentication if the users passwords can be obtained from the security realm, and if the passwords can not be obtained from the security realm then the http interface will fallback to supporting Basic authentication.

The management interfaces can be configured to use the same realm, however this is not required - if needed the different interfaces could be secured with different realms.

Security Realms

The <security-realms /> element is used to hold the definition of one or more security realms. The definition of a security realm follows the following structure.

The <server-identities /> element defines how the server can identify itself. At the moment it is possible to configure a SSL identity to define how the server obtains it's identity from a keystore. It is also possible to configure a secret identity which is what secret or password the server uses when communicating with another server.

The <authentication /> element is used to define how users connecting to the server will be authenticated.

Authentication

Initially three different mechanisms are supported for defining how the users connecting to the server are authenticated.

  • LDAP - Authentication is performed against an LDAP server to verify the users identity.
  • Users - The usernames and passwords of the users are defined within the domain model, this is only intended as a simple testing mechanism.
  • Properties - The usernames and passwords are defined in a properties file local to the server installation.

The following table outlines which mechanisms are compatible with which interface and the mechanism that will be used at the transport level to authenticate the end user.

Authentication
Mechanism
HTTP
Interface
Native
Interface
LDAP
HTTP BASIC
SASL DIGEST 
Users
HTTP DIGEST
SASL DIGEST
Properties
HTTP DIGEST
SASL DIGEST

Please note that both the HTTP Basic and the SASL Plain  mechanisms transmit the users password in a form that is easily reversed.

The following sections illustrate how each of these authentication mechanisms are configured.

LDAP

The LDAP authenticator operates by first establishing a connection to the remote directory server. A search is then performed using the username supplied by the user to identify the fully qualified distinguished name of the user. Finally the authenticator establishes a new connection to the directory server, this time using the identified distinguished name along with the password supplied by the user; this verifies that the dn / password for the user is valid.

Here is a sample configuration showing a security realm with the LDAP authenticator defined.

The following attributes can be specified on the ldap element: -

  • connection - The name of the connection defined in <outbound-connections> to use to connect to the LDAP directory.
  • base-dn - The distinguished name of the context to begin searching for the user.
  • username-attribute - The attribute of the user in the directory to match against the supplied username.
  • recursive (default - false) - Should the search recurs into sub-contexts or just search the specified context.
  • user-dn (default - dn) - The attribute of the user that holds the distinguished name, this is subsequently used to test authentication as the user can complete.
Users

The Users authenticator is a simple authenticator to validate the user against usernames and password stored within the domain model. This authenticator is only intended for some very simple testing.

Here is a sample configuration showing a security realm with the Users authenticator defined: -

Here each user is simply defined using the <user> element, the user name is specified using the 'username' attribute and the password is defined in a nested <password> element.

Properties

The Properties authenticator is very similar to the Users authenticator except that the usernames and passwords are now defined within a properties file. The benefit of this over the Users mechanism is that sensitive passwords are not leaking into the domain model.

Here is a sample configuration showing a security realm with the Properties authenticator defined:

Here the properties file is simply specified where the 'path' attribute is the path to the file and the 'relative-to' attribute references a pre-defined path that the path attribute is relative to. In this example the users.properties can be found in the same folder as the standalone.xml file. If the 'relative-to' attribute is not specified, the value of the 'path' attribute must be an absolute path.

Server Identities

The <server-identities> element is used to define identities that the server uses to identify itself in various scenarios. Currently an SSL identity can be defined that is used to enable SSL on the HTTP interface and a Secret identity can be defined which holds a password that can be used when a host controller is establishing a connection to a remote domain controller.

SSL

The SSL identity currently takes configuration required to load a static keystore from the local filesystem. Later this will be enhanced to allow for different keystore types.

An example SSL definition is shown here: -

The location of the actual keystore is defined in the same way the location of the properties file for the properties authenticator is defined with a path to the keystore and an optional relative-to attribute to make the path relative to a known location.

Secret

The Secret identity is used when a slave domain controller needs to establish a connection to a secured master domain controller.

To show this in context the following shows all the additional configuration on the slave domain controller:

Here the <remote> definition for the domain controller references the defined security realm, this reference means that the specified security realm will be used to load the client side of the configuration (Later this will be expanded so the realm can also define SSL configuration for the client side of the connection).

The value specified for the secret is the password encoded using Base64. On attempting to connect to the remote domain controller the Base64 password will be decoded and the connection will authenticate using the name of the host (in this example 'slave') and the password obtained from the secret.  The master domain controller will also need to be configured with a realm that contains the user 'slave' with the specified password.

Under the following issue AS7-1102 the password handling will be enhanced to allow better protection of configuration passwords from obfuscation using password based encryption through to encryption using external security providers, smart cards or hardware security modules over PKCS#11.

Outbound Connections

As described previously the outbound connections configuration is used to define connection to remote servers, presently only LDAP connections are supported but connection to databases will be added to allow for authentication using information stored in a databse.

LDAP

The following configuration shows a sample connection definition to an LDAP server: -

The following attributes can be set on the ldap element: -

  • name - The name to identify this connection, the ldap authenticator will use this name to reference the connection.
  • url - The URL to connect to the directory server.
  • search-dn - The distinguished name of the user to use to perform initial searches.
  • search-credential - The password of the user to connect for the search.
  • initial-context-factory (default - com.sun.jndi.ldap.LdapCtxFactory) - The initial context factory to use when establishing the connection.

Questions

  1. The individual application servers establish a connection to the native interface exposed by their host controller - how are they authenticated?

Before the JBoss AS 7 process is created a random key is generated and passed to the application server instance that is started, the application server then uses this to authenticate when connecting to the native interface.

JVM settings

Configuration of the JVM settings is different for a managed domain and a standalone server. In a managed domain, the domain controller components are responsible for starting and stoping server processes and hence determine the JVM settings. For a standalone server, it's the responsibility of the process that started the server (e.g. passing them as command line arguments).

Managed Domain

In a managed domain the JVM settings can be declared at different scopes: For a specific server group, for a host or for a particular server. If not declared, the settings are inherited from the parent scope. This allows you to customize or extend the JVM settings within every layer.

Let's take a look at the JVM declaration for a server group:

(See domain/configuration/domain.xml)

In this example the server group "main-server-group" declares a heap size of 64m and a maximum heap size of 512m. Any server that belongs to this group will inherit these settings. You can change these settings for the group as a whole, or a specific server or host:

(See domain/configuration/host.xml)

In this case, server-two, belongs to the main-server-group and inherits the JVM settings named default, but declares a lower maximum heap size.

Standalone Server

For a standalone sever you have to pass in the JVM settings either as command line arguments when executing the $JBOSS_HOME/bin/standalone.sh script, or by declaring them in $JBOSS_HOME/bin/standalone.conf. (For Windows users, the script to execute is %JBOSS_HOME%/bin/standalone.bat while the JVM settings can be declared in %JBOSS_HOME%/bin/standalone.conf.bat.)

Command line parameters

To start up a JBoss AS 7 managed domain you need to execute the $JBOSS_HOME/bin/domain.sh script, and to start up a standalone server use $JBOSS_HOME/bin/standalone.sh. This will start it up using the default configuration. As we will see below you can override these defaults by passing in extra arguments on the command line.

System properties

Both the standalone and the managed domain modes use a default configuration which set up standard locations. This section describes the default values of those system properties. Each of the system properties can be overridden by passing them in individually using the standard jvm -Dkey=value options:

The above will start up a standalone server instance using a non-standard AS home directory, and a custom configuration directory. The meaning of the system properties will be described below.

Alternatively, you can tell it about a properties file by any of the following mechanisms:

The properties file is a standard Java property file containing key=value pairs:

Standalone

Property name Usage Default value
java.ext.dirs Use to specify JDK extension directory paths null
jboss.home.dir The root directory of the JBoss AS 7 installation. Set by standalone.sh to $JBOSS_HOME
jboss.server.base.dir The base directory for server content. jboss.home.dir/standalone
jboss.server.config.dir The base configuration directory. jboss.server.base.dir/configuration
jboss.server.data.dir The directory used for persistent data file storage. jboss.server.base.dir/data
jboss.server.log.dir The directory containing the server.log file. jboss.server.base.dir/log
jboss.server.temp.dir The directory used for temporary file storage. jboss.server.base.dir/tmp
jboss.server.deploy.dir The directory used to store deployed content jboss.server.data.dir/content

Managed Domain

Property name Usage Default value
jboss.home.dir The root directory of the JBoss AS 7 installation. Set by domain.sh to $JBOSS_HOME
jboss.domain.base.dir The base directory for domain content. jboss.home.dir/domain
jboss.domain.config.dir The base configuration directory jboss.domain.base.dir/configuration
jboss.domain.data.dir The directory used for persistent data file storage. jboss.domain.base.dir/data
jboss.domain.log.dir The directory containing the host-controller.log and process-controller.log files jboss.domain.base.dir/log
jboss.domain.temp.dir The directory used for temporary file storage jboss.domain.base.dir/tmp
jboss.domain.deployment.dir The directory used to store deployed content jboss.domain.base.dir/content
jboss.domain.servers.dir The directory containing the output for the managed server instances jboss.domain.base.dir/log

Other command line parameters

The first acceptable format is

For example:

If the parameter name is a single character, it is prefixed by a single '-' instead of two:

For example:

The sections below describe the command line parameter names that are available in standalone and domain mode.

Standalone

Name Default if absent Value
--server-config jboss.server.config.dir/standalone.xml Either a relative path which is interpreted to be relative to jboss.server.config.dir or an absolute path.

Managed Domain

Name Default if absent Value
--domain-config jboss.domain.config.dir/domain.xml Either a relative path which is interpreted to be relative to jboss.domain.config.dir or an absolute path.
--host-config jboss.domain.config.dir/host.xml Either a relative path which is interpreted to be relative to jboss.domain.config.dir or an absolute path.

The following parameters take no value and are only usable on slave host controllers (i.e. hosts configured to connect to a remote domain controller.)

Name Function
--backup Causes the slave host controller to create and maintains a local copy of the domain configuration file
--cached-dc If the slave host controller is unable to contact the master domain controller to get its configuration on boot, boot from a local copy previously created using --backup. The slave host controller will not be able make any modifications to the domain configuration, but it will be able to launch servers.

Common parameters

These parameters are usable in either standalone or managed domain mode, and have no values. The following table explains what each of these does

Name Function
--version
-V
Prints out the version of JBoss AS and exits the JVM.
--help
-h
Prints out a help message explaining the options and exits the JVM.

Subsystem configuration

The following chapters will focus on the high level management use cases that are available through the CLI and the web interface. For a detailed description of each subsystem configuration property, please consult the respective component reference.

Schema Location
The configuration schema can found in $JBOSS_HOME/docs/schema.

Data sources

Datasources are configured through the datasource subsystem. Declaring a new datasource consists of two separate steps: You would need to provide a JDBC driver and define a datasource that references the driver you installed. 

JDBC Driver Installation

The recommended way to install a JDBC driver into the application server is to simply deploy it as a regular JAR deployment.  The reason for this is that when you run your application server in domain mode, deployments are automatically propagated to all servers to which the deployment applies; thus distribution of the driver JAR is one less thing for you to worry about!

Any JDBC 4-compliant driver will automatically be recognized and installed into the system by name and version. A JDBC JAR is identified using the Java service provider mechanism. Such JARs will contain a text a file named META-INF/services/java.sql.Driver, which contains the name of the class(es) of the Drivers which exist in that JAR. If your JDBC driver JAR is not JDBC 4-compliant, it can be made deployable in one of a few ways.

Modify the JAR

The most straightforward solution is to simply modify the JAR and add the missing file. You can do this from your command shell by:

  1. Change to, or create, an empty temporary directory.
  2. Create a META-INF subdirectory.
  3. Create a META-INF/services subdirectory.
  4. Create a META-INF/services/java.sql.Driver file which contains one line - the fully-qualified class name of the JDBC driver.
  5. Use the jar command-line tool to update the JAR like this:

For a detailed explanation how to deploy JDBC 4 compliant driver jar, please refer to the chapter "Application Deployment".

Datasource Definitions

The datasource itself is defined within the subsystem datasources:

(See standalone/configuration/standalone.xml)

As you can see the datasource references a driver by it's logical name.

You can easily query the same information through the CLI:

Using the web console or the CLI greatly simplifies the deployment of JDBC drivers and the creation of datasources.

The CLI offers a set of commands to create and modify datasources:

Component Reference

The datasource subsystem is provided by the IronJacamar project. For a detailed description of the available configuration properties, please consult the project documentation.

Messaging

The JMS server configuration is done through the messaging subsystem. In this chapter we are going outline the frequently used configuration options. For a more detailed explanation please consult the HornetQ user guide (See "Component Reference"). 

Connection Factories

The JMS connection factories can be split into two kinds: In-VM connections and connections factories that can be used by remote clients. Each connection factory does reference a connector declaration, that is associated with a socket binding. The connection factory entry declaration specifies the JNDI name under which the factory will be exposed.

(See standalone/configuration/standalone.xml)

Queues and Topics

Queues and topics are sub resources of the messaging subsystem.
Each entry refers to a JNDI name of the queue or topic:

(See standalone/configuration/standalone.xml)

JMS endpoints can easily be created through the CLI:

A number of additional commands to maintain the JMS subsystem are available as well:

Dead Letter & Redelivery

Some of the settings are applied against an address wild card instead of a specific messaging destination. The dead letter queue and redelivery settings belong into this group:

(See standalone/configuration/standalone.xml)

Security Settings

Security constraints are matched against an address wildcard, similar to the DLQ and redelivery settings.

(See standalone/configuration/standalone.xml)

Component Reference

The messaging subsystem is provided by the HornetQ project. Fo a detailed description of the available configuration properties, please consult the project documentation.

Web

The web subsystem configuration basically consists of three parts: The JSP Configuration, connectors and virtual servers. Advanced topics like load balancing and failover are covered on the "High Availability Guide". The default configuration does is suitable for most use cases and provides reasonable performance settings.

Required extension:

Basic subsystem configuration example:

Dependencies on other subsystems:

None

Container configuration
JSP Configuration

The "configuration" subresource covers all aspects that relate to the configuration of the servlet engine itself. For a detailed explanation of each configuration attribute, please consult the JBossWeb documentation (See "Component Reference").

(See standalone/configuration/standalone.xml)

Connector configuration

The connectors are child resources of the subsystem web. Each connector does reference a particular socket binding:

Creating a new connector requires you to declare a new socket binding first:

The newly created, unused socket binding can then be used to create a new connector configuration:

Statistic information can be displayed from the connectors:

The following attributes can be queried:

value
description
bytesSent Number of byte sent by the connector
bytesReceived Number of byte received by the connector (POST data).
processingTime Processing time used by the connector. Im milli-seconds.
errorCount Number of error that occurs when processing requests by the connector.
maxTime Max time spent to process a request.
requestCount Number of requests processed by the connector.

For example:

There are 3 different connectors available:

HTTP Connectors

This one is the default connector, it runs usually on port 8080. See above how to configure it.

HTTPS Connectors

The HTTPS connectors are child resources of the subsystem web. By default they use JSSE. Each connector does reference a particular socket binding:

Creating a new connector may require you to declare a new socket binding first:

The newly created, unused socket binding can then be used to create a new connector configuration:

The default for SSL is to use Alias "tomcat" and password "changeit". It is possible to create the corresponding keystore using keytool:

Of course specify a password value of "changeit".

AJP Connectors

The AJP connectors are child resources of the subsystem web. They are used with mod_jk, mod_proxy and mod_cluster of the Apache httpd front-end. Each connector does reference a particular socket binding:

Creating a new connector requires you to declare a new socket binding first:

The newly created, unused socket binding can then be used to create a new connector configuration:

Native Connectors

Native connectors are high performance connectors based on Tomcat native. They are used if the native modules are installed, a lot of distributions have it included, in case you don't have it try JBoss Web Native.

At a configuration level only the SSL part needs to be configured differently because it use OpenSSL.

Virtual-Server configuration

Similar to the connectors, the virtual server declarations are child resources of the web subsystem. They will be referenced by alias names and can optionally refer to a default web application that acts serves the root web context.

Adding a virtual server declaration is can be done through the default :add() operation

add/remove operations exists on any node in the configuration tree.
Component Reference

The web subsystem is provided by the JBossWeb project. Fo a detailed description of the available configuration properties, please consult the JBossWeb documentation.

Web services

Web service endpoint are exposed through the deployments that provide endpoint implementation. Thus they can be queried as deployment resources. For further information please consult the chapter "Application Deployment". Each web service endpoint specifies a web context and a WSDL Url:

Component Reference

The web service subsystem is provided by the JBossWS project. Fo a detailed description of the available configuration properties, please consult the project documentation.

Logging

The overall server logging configuration is represented by the logging subsystem. It consists of three notable parts: handler configurations, logger and the root logger declarations (aka log categories). Each logger does reference a handler (or set of handlers). Each handler declares the log format and output:

Default Log File Locations

Managed Domain

In a managed domain two types of log files do exist: Controller and server logs. The controller components govern the domain as whole. It's their responsibility to start/stop server instances and execute managed operations throughout the domain. Server logs contain the logging information for a particular server instance. They are co-located with the host the server is running on.

For the sake of simplicity we look at the default setup for managed domain. In this case, both the domain controller components and the servers are located on the same host:

Process Log File
Host Controller ./domain/log/host-controller/boot.log
Process Controller ./domain/log/process-controller/boot.log
"Server One" ./domain/servers/server-one/log/boot.log
"Server One" ./domain/servers/server-one/log/server.log
"Server Three" ./domain/servers/server-three/log/boot.log
"Server Three" ./domain/servers/server-three/log/server.log


The server logs as you know it from previous JBoss AS versions are located in the servers subdirectory: I.e. ./domain/servers/server-three/log/server.log


Standalone Server 

The default log files for a standalone server can be found in the log subdirectory of the distribution:

Process Log File
Server ./standalone/log/boot.log
Server ./standalone/log/server.log

JMX

The JMX subsystem sets up a JMX connector so that invocations can be done on the JMX MBean server from outside the JVM

To use the connector you can access it in the standard way:

You can also connect using jconsole. In addition to the standard JVM MBeans, the JBoss AS 7 MBean server contains the following MBeans:

JMX ObjectName Description
jboss.msc:type=container,name=jboss-as Exposes management operations on the JBoss Modular Service Container, which is the dependency injection framework at the heart of JBoss AS 7. It is useful for debugging dependency problems, for example if you are integrating your own subsystems, as it exposes operations to dump all services and their current states
jboss.naming:type=JNDIView Shows what is bound in JNDI
jboss.modules:type=ModuleLoader,name=* This collection of MBeans exposes management operations on JBoss Modules classloading layer. It is useful for debugging dependency problems arising from missing module dependencies

OSGi

Old Documentation
This documentation applies to AS 7.0 only and has been superceded by documentation that can be found
in the JBoss OSGi Documentation Pages.

OSGi functionality in JBoss AS 7 is provided through the OSGi subsystem.

More information on the OSGi component in JBoss AS 7 can be found on the JBoss OSGi project pages.

The OSGi subsystem can be configured in its section in the JBoss AS 7 configuration XML file.

The following items can be configured:

Subsystem Attributes

Attribute Description
activation When set to lazy the OSGi subsystem will not get activated until the first OSGi bundle deployment. When set to eager the OSGi subsystem will be activated at startup of the Application Server.

Configuration Admin

The OSGi Configuration Admin Service (CAS) is a standard service aimed at configuring OSGi-based applications. Many OSGi applications use the CAS to configure themselves.

The OSGi subsystem configuration allows for the specification of CAS configuration information, to configure bundles written for this specification (chapter 104 in the OSGi 4.2 Compendium Specification)

To add CAS configuration information, add <configuration> tags to the OSGi subsystem configuration. For example, the following is used to configure the context root where the Felix Web Console appears:

Configuration information consists of a <configuration> tag specifying a PID (Persistent Identifier) attribute which identifies the system to be configured. The configuration tag can contain any number of embedded <property> tags which hold the configuration information for this PID.

Framework Properties

OSGi Framework properties are specified as embedded <property> elements in the <properties> tag.

The following properties are specified:

Property Description
org.jboss.osgi.system.modules A comma-separated list of module identifiers. Each system module is added as a dependency to the OSGi framework module. The packages from these system modules can be made visible as framework system packages by adding them to the org.osgi.framework.system.packages.extra property.
org.osgi.framework.system.packages.extra Extra packages which the system bundle must export from the current execution environment.
org.osgi.framework.startlevel.beginning The beginning start level of the OSGi Framework. This also influences which modules are pre-loaded. See the modules section.

Additional OSGi Framework properties can be specified. For more information on OSGi Framework properties see the OSGi 4.2 Core Specification.

Modules

JBoss AS 7 comes with a repository of modules and OSGi bundles that can be automatically loaded at startup. JBoss-Modules compliant modules can be found in the modules/ directory and OSGi bundles can be found in the bundles/ directory. In the <modules> section of the XML configuration both JBoss-Modules as well as OSGi Bundles can be specified.

OSGi Bundles can also be started automatically at startup. This is specified with the startlevel attribute. The default start level of the OSGi Framework is 1. To enable additional functionality in the OSGi Framework, increase the org.osgi.framework.startlevel.beginning framework property.

Note that these modules don't trigger the activation of the OSGi subsystem. Once the subsystem is activated as described above, these modules and bundles will be automatically loaded and optionally started.

The following modules and bundles are listed in the default configuration.

Module Identifier Description
javaee.api Provides JavaEE APIs.
org.apache.aries.jmx Provides JMX support to OSGi as described in chapter 124 of the OSGi 4.2 Enterprise Specification. For more information see Using JMX below.
org.apache.aries.util Needed by the Aries JMX bundle.
org.apache.felix.configadmin An implementation of the OSGi Configuration Admin specificaton. Chapter 104 in the OSGi 4.2 Compendium Specification.
org.apache.felix.eventadmin An implementation of the OSGi Event Admin specification. Chapter 113 in the OSGi 4.2 Compendium Specification.
org.apache.felix.log An implementation of the OSGi Log Service specification. Chapter 101 in the OSGi 4.2 Compendium Specification.
org.apache.felix.metatype An implementation of the OSGi Metatype Service specification. Chapter 105 in the OSGi 4.2 Compendium Specification.
org.apache.felix.webconsole The Felix Web Console. For more information see Using the Felix Web Console below.
org.jboss.as.osgi.configadmin Component providing the OSGi Configuration Admin Service with information from the OSGi subsystem configuration.
org.jboss.logging The JBoss Logging Framework.
org.jboss.osgi.blueprint An implementation of the OSGi Blueprint Specification. Blueprint is a component model and IoC specification for OSGi which significantly simplifies the use of OSGi services. It can be found in chapter 121 in the OSGi 4.2 Enterprise Specification.
org.jboss.osgi.http An implementation of the OSGi Http Service. Chapter 102 in the OSGi 4.2 Compendium Specification. The port used by this implementation is set by default to <socket-binding name="osgi-http" port="8090"/> in the socket-binding-group.
org.jboss.osgi.jmx Enhanced JMX API, the MBeans can be found under jboss.osgi.
org.jboss.osgi.logging Sends log messages sent to the OSGi Log Service to JBoss Logging.
org.jboss.osgi.webapp OSGi Support for Web Apps, as described in chapter 128 in the OSGi 4.2 Compendium Specification.
org.jboss.osgi.webconsole Customizations of the Felix Web Console.
org.jboss.osgi.xerces An implementation of the OSGi XML Parser specification. Chapter 702 in the OSGi 4.2 Compendium Specification.
org.osgi.compendium A bundle providing the APIs defined by the OSGi Compendium Specification.

Using the Felix Web Console

For fine-grained management of the OSGi Framework, the Apache Felix Web Console can be used. This web console is shipped as part of JBoss AS 7 and is specifically aimed at fine-grained control of the OSGi Framework.

The Web Console is not enabled by default. The relevant modules are marked as having startlevel=2, so to enable the web console set the initial framework start level to 2 or higher:

By default the console appears on http://localhost:8090/jboss-osgi with as username and password admin/admin. This can be configured through the OSGi Configuration Admin Service configuration.

Start JBoss AS 7 and make sure the OSGi Framework is active; the framework can be activated by deploying an OSGi bundle into JBoss AS 7 or by setting its activation mode to eager.

Then open a web browser and access: http://localhost:8090/jboss-osgi. A log-in dialog appears. Enter the password configured or the default username and password: admin/admin and the web console will appear:

Using JMX

The OSGi Framework exposes a number of JMX MBeans that enable remote control of the framework. Both the MBeans that are defined in chapter 124 of the OSGi 4.2 Enterprise Specification as well as JBoss-extended MBeans are available.

The JMX support is not enabled by default. The relevant modules are marked as having startlevel=2, so to enable JMX set the initial framework start level to 2 or higher:

Start JBoss AS 7 and make sure the OSGi Framework is active; the framework can be activated by deploying an OSGi bundle into JBoss AS 7 or by setting its activation mode to eager.

The JMX functionality can now be accessed through a JMX console, for instance jconsole which ships with the JDK:

Connect using the Remote Process URL service:jmx:rmi:///jndi/rmi://127.0.0.1:1090/jmxrmi. (You can also connect directly to the Local Process, the one that starts with jboss-modules.jar -mp ...)

When the connection is established navigate to the MBeans tab to interact with the OSGi MBeans.

Deployment Scanner

The deployment scanner is only used in standalone mode. Its job is to monitor a directory for new files and to deploy those files. It can be found in standalone.xml:

The subsystem can be removed complete from the standalone configuration, e.g. for security reasons. In this case all deployments are only possible via CLI or Console as in the domain mode.
You can define more deployment-scanner entries, by using different name identifier, to scan for deployments from more locations. The configuration showed will scan the $JBOSS_HOME/standalone/deployments directory every five seconds. The runtime model is shown below, and uses default values for attributes not specified in the xml:

The attributes are

Name Type Description
name STRING The name of the scanner. default is used if not specified
path STRING The actual filesystem path to be scanned. Treated as an absolute path, unless the 'relative-to' attribute is specified, in which case the value is treated as relative to that path.
relative-to STRING Reference to a filesystem path defined in the "paths" section of the server configuration, or one of the system properties specified on startup. In the example above jboss.server.base.dir resolves to {{$JBOSS_HOME/standalone
scan-enabled BOOLEAN If true scanning is enabled
scan-interval INT Periodic interval, in milliseconds, at which the repository should be scanned for changes. A value of less than 1 indicates the repository should only be scanned at initial startup.
auto-deploy-zipped BOOLEAN Controls whether zipped deployment content should be automatically deployed by the scanner without requiring the user to add a .dodeploy marker file.
auto-deploy-exploded BOOLEAN Controls whether exploded deployment content should be automatically deployed by the scanner without requiring the user to add a .dodeploy marker file. Setting this to 'true' is not recommended for anything but basic development scenarios, as there is no way to ensure that deployment will not occur in the middle of changes to the content.
deployment-timeout LONG Timeout, in seconds, a deployment is allows to execute before being canceled. The default is 60 seconds.

Deployment scanners can be added by modifying standalone.xml before starting up the server or they can be added and removed at runtime using the CLI

You can also change the attributes at runtime, so for example to turn off scanning you can do

Simple configuration subsystems

The following subsystems currently have no configuration beyond its root element in the configuration

The presence of each of these turns on a piece of functionality:

Name Description
EE Enables the deployment of .EAR archives.
EJB3 Enables the deployment and functionality of EJB 3.1 applications.
JAXRS Enables the deployment and functionality of JAX-RS applications. This is implemented by the RestEasy project
Remoting Turns on the remoting subsystem, which is used for the management communication and will be what underlies remote JNDI lookups and remote EJB calls in a future release.
Sar Enables the deployment of .SAR archives containing MBean services, as supported by previous versions of JBoss Application Server
Threads This subsystem is being deprecated and will not be part of the next release
Weld Enables the deployment and functionality of CDI applications

Configuration file history

The management operations may modify the model. When this occurs the xml backing the model is written out again reflecting the latest changes. In addition a full history of the file is maintained. The history of the file goes in a separate directory under the configuration directory.

As mentioned in Command line parameters#parameters the default configuration file can be selected using a command-line parameter. For a standalone server instance the history of the active standalone.xml is kept in jboss.server.config.dir/standalone_xml_history (See Command line parameters#standalone_system_properties for more details). For a domain the active domain.xml and host.xml histories are kept in jboss.domain.config.dir/domain_xml_history and jboss.domain.config.dir/host_xml_history.

The rest of this section will only discuss the history for standalone.xml. The concepts are exactly the same for domain.xml and host.xml.

Within standalone_xml_history itself following a successful first time boot we end up with three new files:
*standalone.initial.xml - This contains the original configuration that was used the first time we successfully booted. This file will never be overwritten. You may of course delete the history directory and any files in it at any stage.
*standalone.boot.xml - This contains the original configuration that was used for the last successful boot of the server. This gets overwritten every time we boot the server successfully.
*standalone.last.xml - At this stage the contents will be identical to standalone.boot.xml

standalone_xml_history contains a directory called current which should be empty. Now if we execute a management operation that modifies the model, for example adding a new system property using the CLI:

What happens is:
*The original configuration file is backed up to standalone_xml_history/current/standalone.v1.xml. The next change to the model would result in a file called standalone.v2.xml etc. The 100 most recent of these files are kept.
*The change is applied to the original configuration file
*The changed original configuration file is copied to standalone_xml_history/current/standalone.last.xml

When restarting the server any existing standalone_xml_history/current directory is moved to a new timestamped folder within the standalone_xml_history, and a new current folder is created. These timestamped folders are kept for 30 days.

You can restart the server by using any of the backed up versions by passing in the relative filename under jboss.server.config.dir, for example:

Snapshots

Each successful boot results in a timestamped version of the original configuration file within the standalone_xml_history/snapshot/ directory. Again the relative name of any of these under jboss.server.config.dir may be used as the argument for --server-config.

You may also take your own snapshots using the CLI:

You can also use the CLI to list all the snapshots

 To delete a particular snapshot:

and to delete all snapshots:

In domain mode executing the snapshot operations against the root node will work against the domain model. To do this for a host model you need to navigate to the host in question:

Starting & stopping Servers in a Managed Domain

Starting a standalone server is done through the bin/standalone.sh script. However in a managed domain server instances are managed by the domain controller and need to be started through the management layer:

First of all, get to know which servers are configured on a particular host:

Now that we know, that there are two servers configured on host "local", we can go ahead and check their status:

You can change the server state through the "start" and "stop" operations

Navigating through the domain topology is much more simple when you use the web interface.

Application deployment

Managed Domain

In managed domain deployments are associated with a server group (See "Core Management Concepts"). Deployments will be provided to any server that belongs to a particular group. The domain and host controller components manage the distribution of binaries across network boundaries.

Deployment Commands

The process of distributing deployment binaries involves two steps: You need to upload the deployment to the repository from which the domain controller can distribute its contents. In a second step you need to assign the deployment to one or more server groups:

Using the CLI you can do it one sweep:

After you've uploaded the binary using the "deploy" command, it will be available to the domain controller
and assigned to a server group:

In a similar way it can be removed from the server group:

Managing deployments through the web interface provides an alternate, sometimes more simple approach.

Content Repository

Any deployment is referenced from the domain configuration file and stored co-located with the domain controller:

(See domain/configuration/domain.xml)

The actual binaries are stored in the content subdirectory:

Standalone Server

Deployment on a standalone server works similar to the managed domain, just that the server-group associations don't exist.

Deployment Commands

You can rely on the same CLI command as for a managed domain to deploy an application:

File System Deployments

The standalone/deployments directory in the JBoss Application Server 7 distribution is the location end users can place their deployment content (e.g. war, ear, jar, sar files) to have it automically deployed into the server runtime.

Users, particularly those running production systems, are encouraged to use the JBoss AS 7 management APIs to upload and deploy deployment content instead of relying on the deployment scanner subsystem that periodically scans this directory.
Deployment Modes

The filesystem deployment scanner in JBoss AS 7 and later works differently from previous JBoss AS releases. The scanner can operate in one of two different modes, depending on whether it will directly monitor the deployment content in order to decide to deploy (or redeploy) it.

Auto-deploy mode:

The scanner will directly monitor the deployment content, automatically deploying new content and redeploying content whose timestamp has changed. This is similiar to the behavior of previous AS releases, although there are differences:

  • A change in any file in an exploded deployment triggers redeploy. Because EE 6 applications do not require deployment descriptors,
    there is no attempt to monitor deployment descriptors and only redeploy when a deployment descriptor changes.
  • The scanner will place marker files in this directory as an indication of the status of its attempts to deploy or undeploy content. These are detailed below.

Manual deploy mode:

The scanner will not attempt to directly monitor the deployment content and decide if or when the end user wishes the content to be deployed. Instead, the scanner relies on a system of marker files, with the user's addition or removal of a marker file serving as a sort of command telling the scanner to deploy, undeploy or redeploy content.

Auto-deploy mode and manual deploy mode can be independently configured for zipped deployment content and exploded deployment content. This is done via the "auto-deploy" attribute on the deployment-scanner element in the standalone.xml configuration file:

By default, auto-deploy of zipped content is enabled, and auto-deploy of exploded content is disabled. Manual deploy mode is strongly recommended for exploded content, as exploded content is inherently vulnerable to the scanner trying to auto-deploy partially copied content.

Marker Files

The marker files always have the same name as the deployment content to which they relate, but with an additional file suffix appended. For example, the marker file to indicate the example.war file should be deployed is named example.war.dodeploy. Different marker file suffixes have different meanings.

The relevant marker file types are:

File Purpose
.dodeploy Placed by the user to indicate that the given content should
be deployed into the runtime (or redeployed if already
deployed in the runtime.)
.skipdeploy Disables auto-deploy of the content for as long as the file
is present. Most useful for allowing updates to exploded
content without having the scanner initiate redeploy in the
middle of the update. Can be used with zipped content as
well, although the scanner will detect in-progress changes
to zipped content and wait until changes are complete.
.isdeploying Placed by the deployment scanner service to indicate that it
has noticed a .dodeploy file or new or updated auto-deploy
mode content and is in the process of deploying the content.
This marker file will be deleted when the deployment process
completes.
.deployed Placed by the deployment scanner service to indicate that the
given content has been deployed into the runtime. If an end
user deletes this file, the content will be undeployed.
.failed Placed by the deployment scanner service to indicate that the
given content failed to deploy into the runtime. The content
of the file will include some information about the cause of
the failure. Note that with auto-deploy mode, removing this
file will make the deployment eligible for deployment again.
.isundeploying Placed by the deployment scanner service to indicate that it
has noticed a .deployed file has been deleted and the
content is being undeployed. This marker file will be deleted
when the undeployment process completes.
.undeployed Placed by the deployment scanner service to indicate that the
given content has been undeployed from the runtime. If an end
user deletes this file, it has no impact.
.pending Placed by the deployment scanner service to indicate that it
has noticed the need to deploy content but has not yet
instructed the server to deploy it. This file is created if
the scanner detects that some auto-deploy content is still in
the process of being copied or if there is some problem that
prevents auto-deployment. The scanner will not instruct the
server to deploy or undeploy any content (not just the
directly affected content) as long as this condition holds.

Basic workflows:
All examples assume variable $AS points to the root of the JBoss AS 7 distribution.

A) Add new zipped content and deploy it:

  1. cp target/example.war/ $AS/standalone/deployments
  2. (Manual mode only) touch $AS/standalone/deployments/example.war.dodeploy

B) Add new unzipped content and deploy it:

  1. cp -r target/example.war/ $AS/standalone/deployments
  2. (Manual mode only) touch $AS/standalone/deployments/example.war.dodeploy

C) Undeploy currently deployed content:

  1. rm $AS/standalone/deployments/example.war.deployed

D) Auto-deploy mode only: Undeploy currently deployed content:

  1. rm $AS/standalone/deployments/example.war

E) Replace currently deployed zipped content with a new version and deploy it:

  1. cp target/example.war/ $AS/standalone/deployments
  2. (Manual mode only) touch $AS/standalone/deployments/example.war.dodeploy

F) Manual mode only: Replace currently deployed unzipped content with a new version and deploy it:

  1. rm $AS/standalone/deployments/example.war.deployed
  2. wait for $AS/standalone/deployments/example.war.undeployed file to appear
  3. cp -r target/example.war/ $AS/standalone/deployments
  4. touch $AS/standalone/deployments/example.war.dodeploy

G) Auto-deploy mode only: Replace currently deployed unzipped content with a new version and deploy it:

  1. touch $AS/standalone/deployments/example.war.skipdeploy
  2. cp -r target/example.war/ $AS/standalone/deployments
  3. rm $AS/standalone/deployments/example.war.skipdeploy

H) Manual mode only: Live replace portions of currently deployed unzipped content without redeploying:

  1. cp -r target/example.war/foo.html $AS/standalone/deployments/example.war

I) Auto-deploy mode only: Live replace portions of currently deployed unzipped content without redeploying:

  1. touch $AS/standalone/deployments/example.war.skipdeploy
  2. cp -r target/example.war/foo.html $AS/standalone/deployments/example.war

J) Manual or auto-deploy mode: Redeploy currently deployed content (i.e. bounce it with no content change):

  1. touch $AS/standalone/deployments/example.war.dodeploy

K) Auto-deploy mode only: Redeploy currently deployed content (i.e. bounce it with no content change):

  1. touch $AS/standalone/deployments/example.war
The above examples use Unix shell commands. Windows equivalents are:

cp src dest --> xcopy /y src dest
cp -r src dest --> xcopy /e /s /y src dest
rm afile --> del afile
touch afile --> echo>> afile

Note that the behavior of 'touch' and 'echo' are different but the differences are not relevant to the usages in the examples above.

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.