Skip to end of metadata
Go to start of metadata

Operating modes

JBoss Application Server 7 can be booted in two different modes. A managed domain allows you to run and manage a multi-server topology. Alternatively, you can run a standalone server instance.

Standalone Server

For many use cases, the centralized management capability available via a managed domain is not necessary. For these use cases, a JBoss Application Server 7 instance can be run as a "standalone server". A standalone server instance is an independent process, much like an JBoss Application Server 3, 4, 5, or 6 instance is. Standalone instances can be launched via the standalone.sh or standalone.bat launch scripts.

If more than one standalone instance is launched and multi-server management is desired, it is the user's responsibility to coordinate management across the servers. For example, to deploy an application across all of the standalone servers, the user would need to individually deploy the application on each server.

It is perfectly possible to launch multiple standalone server instances and have them form an HA cluster, just like it was possible with JBoss Application Server 3, 4, 5 and 6.

Managed Domain

One of the primary new features of JBoss Application Server 7 is the ability to manage multiple JBoss Application Server 7 instances from a single control point. A collection of such servers is referred to as the members of a "domain" with a single Domain Controller process acting as the central management control point. All of the JBoss Application Server 7 instances in the domain share a common management policy, with the Domain Controller acting to ensure that each server is configured according to that policy. Domains can span multiple physical (or virtual) machines, with all JBoss Application Server 7 instances on a given host under the control of a special Host Controller process. One Host Controller instance is configured to act as the central Domain Controller. The Host Controller on each host interacts with the Domain Controller to control the lifecycle of the application server instances running on its host and to assist the Domain Controller in managing them.

When you launch a JBoss Application Server 7 managed domain on a host (via the domain.sh or domain.bat launch scripts) your intent is to launch a Host Controller and usually at least one JBoss Application Server 7 instance. On one of the hosts the Host Controller should be configured to act as the Domain Controller. See Domain Setup for details.

The following is an example managed domain topology:

Host

Each "Host" box in the above diagram represents a physical or virtual host. A physical host can contain zero, one or more server instances.

Host Controller

When the domain.sh or domain.bat script is run on a host, a process known as a Host Controller is launched. The Host Controller is solely concerned with server management; it does not itself handle application server workloads. The Host Controller is responsible for starting and stopping the individual application server processes that run on its host, and interacts with the Domain Controller to help manage them.

Each Host Controller by default reads its configuration from the domain/configuration/host.xml file located in the unzipped JBoss Application Server 7 installation on its host's filesystem. The host.xml file contains configuration information that is specific to the particular host. Primarily:

  • the listing of the names of the actual JBoss Application Server 7 instances that are meant to run off of this installation.
  • configuration of how the Host Controller is to contact the Domain Controller to register itself and access the domain configuration. This may either be configuration of how to find and contact a remote Domain Controller, or a configuration telling the Host Controller to itself act as the Domain Controller.
  • configuration of items that are specific to the local physical installation. For example, named interface definitions declared in domain.xml (see below) can be mapped to an actual machine-specific IP address in host.xml. Abstract path names in domain.xml can be mapped to actual filesystem paths in host.xml.

Domain Controller

One Host Controller instance is configured to act as the central management point for the entire domain, i.e. to be the Domain Controller. The primary responsibility of the Domain Controller is to maintain the domain's central management policy, to ensure all Host Controllers are aware of its current contents, and to assist the Host Controllers in ensuring any running application server instances are configured in accordance with this policy. This central management policy is stored by default in the domain/configuration/domain.xml file in the unzipped JBoss Application Server 7 installation on Domain Controller's host's filesystem.

A domain.xml file must be located in the domain/configuration directory of an installation that's meant to run the Domain Controller. It does not need to be present in installations that are not meant to run a Domain Controller; i.e. those whose Host Controller is configured to contact a remote Domain Controller. The presence of a domain.xml file on such a server does no harm.

The domain.xml file includes, among other things, the configuration of the various "profiles" that JBoss Application Server 7 instances in the domain can be configured to run. A profile configuration includes the detailed configuration of the various subsystems that comprise that profile (e.g. an embedded JBoss Web instance is a subsystem; a JBoss TS transaction manager is a subsystem, etc). The domain configuration also includes the definition of groups of sockets that those subsystems may open. The domain configuration also includes the definition of "server groups":

Server Group

A server group is set of server instances that will be managed and configured as one. In a managed domain each application server instance is a member of a server group. (Even if the group only has a single server, the server is still a member of a group.) It is the responsibility of the Domain Controller and the Host Controllers to ensure that all servers in a server group have a consistent configuration. They should all be configured with the same profile and they should have the same deployment content deployed.

The domain can have multiple server groups. The above diagram shows two server groups, "ServerGroupA" and "ServerGroupB". Different server groups can be configured with different profiles and deployments; for example in a domain with different tiers of servers providing different services. Different server groups can also run the same profile and have the same deployments; for example to support rolling application upgrade scenarios where a complete service outage is avoided by first upgrading the application on one server group and then upgrading a second server group.

An example server group definition is as follows:

A server-group configuration includes the following required attributes:

  • name -- the name of the server group
  • profile -- the name of the profile the servers in the group should run

In addition, the following optional elements are available:

  • socket-binding-group -- specifies the name of the default socket binding group to use on servers in the group. Can be overridden on a per-server basis in host.xml. If not provided in the server-group element, it must be provided for each server in host.xml.
  • deployments -- the deployment content that should be deployed on the servers in the group.
  • system-properties -- system properties that should be set on all servers in the group
  • jvm -- default jvm settings for all servers in the group. The Host Controller will merge these settings with any provided in host.xml to derive the settings to use to launch the server's JVM. See JVM settings for further details.

Server

Each "Server" in the above diagram represents an actual application server instance. The server runs in a separate JVM process from the Host Controller. The Host Controller is responsible for launching that process. (In a managed domain the end user cannot directly launch a server process from the command line.)

The Host Controller synthesizes the server's configuration by combining elements from the domain wide configuration (from domain.xml) and the host-specific configuration (from host.xml).

Deciding between running standalone servers or a managed domain

Which use cases are appropriate for managed domain and which are appropriate for standalone servers? A managed domain is all about coordinated multi-server management -- with it JBoss AS 7 provides a central point through which users can manage multiple servers, with rich capabilities to keep those servers' configurations consistent and the ability to roll out configuration changes (including deployments) to the servers in a coordinated fashion.

It's important to understand that the choice between a managed domain and standalone servers is all about how your servers are managed, not what capabilities they have to service end user requests. This distinction is particularly important when it comes to high availability clusters. It's important to understand that HA functionality is orthogonal to running standalone servers or a managed domain. That is, a group of standalone servers can be configured to form an HA cluster. The domain and standalone modes determine how the servers are managed, not what capabilities they provide.

So, given all that:

  • A single server installation gains nothing from running in a managed domain, so running a standalone server is a better choice.
  • For multi-server production environments, the choice of running a managed domain versus standalone servers comes down to whether the user wants to use the centralized management capabilities a managed domain provides. Some enterprises have developed their own sophisticated multi-server management capabilities and are comfortable coordinating changes across a number of independent JBoss AS 7 instances. For these enterprises, a multi-server architecture comprised of individual standalone servers is a good option.
  • Running a standalone server is better suited for most development scenarios. Any individual server configuration that can be achieved in a managed domain can also be achieved in a standalone server, so even if the application being developed will eventually run in production on a managed domain installation, much (probably most) development can be done using a standalone server.
  • Running a managed domain mode can be helpful in some advanced development scenarios; i.e. those involving interaction between multiple JBoss AS 7 instances. Developers may find that setting up various servers as members of a domain is an efficient way to launch a multi-server cluster.

General configuration concepts

For both a managed domain or a standalone server, a number of common configuration concepts apply:

Extensions

An extension is a module that extends the core capabilities of the server. The JBoss Application Server 7 core is very simple and lightweight; most of the capabilities people associate with an application server are provided via extensions. An extension is packaged as a module in the modules folder. The user indicates that they want a particular extension to be available by including an <extension/> element naming its module in the domain.xml or standalone.xml file.

Profiles and Subsystems

The most significant part of the configuration in domain.xml and standalone.xml is the configuration of one (in standalone.xml) or more (in domain.xml) "profiles". A profile is a named set of subsystem configurations. A subsystem is an added set of capabilities added to the core server by an extension (see "Extensions" above). A subsystem provides servlet handling capabilities; a subsystem provides an EJB container; a subsystem provides JTA, etc. A profile is a named list of subsystems, along with the details of each subsystem's configuration. A profile with a large number of subsystems results in a server with a large set of capabilities. A profile with a small, focused set of subsystems will have fewer capabilities but a smaller footprint.

The content of an individual profile configuration looks largely the same in domain.xml and standalone.xml. The only difference is standalone.xml is only allowed to have a single profile element (the profile the server will run), while domain.xml can have many profiles, each of which can be mapped to one or more groups of servers.

The contents of individual subsystem configurations look exactly the same between domain.xml and standalone.xml.

Paths

A logical name for a filesystem path. The domain.xml, host.xml and standalone.xml configurations all include a section where paths can be declared. Other sections of the configuration can then reference those paths by their logical name, rather than having to include the full details of the path (which may vary on different machines). For example, the logging subsystem configuration includes a reference to the "jboss.server.log.dir" path that points to the server's "log" directory.

JBoss AS 7 automatically provides a number of standard paths without any need for the user to configure them in a configuration file:

  • jboss.home - the root directory of the JBoss AS distribution
  • user.home - user's home directory
  • user.dir - user's current working directory
  • java.home - java installation directory
  • jboss.server.base.dir - root directory for an individual server instance
  • jboss.server.data.dir - directory the server will use for persistent data file storage
  • jboss.server.log.dir - directory the server will use for log file storage
  • jboss.server.tmp.dir - directory the server will use for temporary file storage
  • jboss.domain.servers.dir - directory under which a host controller will create the working area for individual server instances (managed domain mode only)

Users can add their own paths or override all except the first 5 of the above by adding a <path/> element to their configuration file.

 The attributes are:

  • name -- the name of the path.
  • path -- the actual filesystem path. 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 -- (optional) the name of another previously named path, or of one of the standard paths provided by the system.

A <path/> element in a domain.xml need not include anything more than the name attribute; i.e. it need not include any information indicating what the actual filesystem path is: 

Such a configuration simply says, "There is a path named 'x' that other parts of the domain.xml configuration can reference. The actual filesystem location pointed to by 'x' is host-specific and will be specified in each machine's host.xml file." If this approach is used, there must be a path element in each machine's host.xml that specifies what the actual filesystem path is:

A <path/> element in a standalone.xml must include the specification of the actual filesystem path.

Interfaces

A logical name for a network interface/IP address/host name to which sockets can be bound. The domain.xml, host.xml and standalone.xml configurations all include a section where interfaces can be declared. 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 may vary on different machines). An interface configuration includes the logical name of the interface as well as information specifying the criteria to use for resolving the actual physical address to use. See Interfaces and ports for further details.

An <interface/> element in a domain.xml need not include anything more than the name attribute; i.e. it need not include any information indicating what the actual IP address associated with the name is:

Such a configuration simply says, "There is an interface named 'internal' that other parts of the domain.xml configuration can reference. The actual IP address pointed to by 'internal' is host-specific and will be specified in each machine's host.xml file." If this approach is used, there must be an interface element in each machine's host.xml that specifies the criteria for determining the IP address:

An <interface/> element in a standalone.xml must include the criteria for determining the IP address.

Socket Bindings and Socket Binding Groups

A socket binding is a named configuration for a socket.

The domain.xml and standalone.xml configurations both include a section where named socket configurations can be declared. Other sections of the configuration can then reference those sockets by their logical name, rather than having to include the full details of the socket configuration (which may vary on different machines). See Interfaces and ports for full details.

System Properties

System property values can be set in a number of places in domain.xml, host.xml and standalone.xml. The values in standalone.xml are set as part of the server boot process. Values in domain.xml and host.xml are applied to servers when they are launched.

When a system property is configured in domain.xml or host.xml, the servers it ends up being applied to depends on where it is set. Setting a system property in a child element directly under the domain.xml root results in the property being set on all servers. Setting it in a <system-property/> element inside a <server-group/> element in domain.xml results in the property being set on all servers in the group. Setting it in a child element directly under the host.xml root results in the property being set on all servers controlled by that host's Host Controller. Finally, setting it in a <system-property/> element inside a <server/> element in host.xml result in the property being set on that server. The same property can be configured in multiple locations, with a value in a <server/> element taking precedence over a value specified directly under the host.xml root element, the value in a host.xml taking precedence over anything from domain.xml, and a value in a <server-group/> element taking precedence over a value specified directly under the domain.xml root element.

Management resources

When JBoss Application Server parses your configuration files at boot, or when you use one of the AS's Management Clients you are adding, removing or modifying management resources in the AS's internal management model. A JBoss AS management resource has the following characteristics:

Address

All JBoss AS management resources are organized in a tree. The path to the node in the tree for a particular resource is its address. Each segment in a resource's address is a key/value pair:

  • The key is the resource's type, in the context of its parent. So, for example, the root resource for a standalone server has children of type subsystem, interface, socket-binding, etc. The resource for the subsystem that provides the AS's webserver capability has children of type connector and virtual-server. The resource for the subsystem that provides the AS's messaging server capability has, among others, children of type jms-queue and jms-topic.
  • The value is the name of a particular resource of the given type, e.g web or messaging for subsystems or http or https for web subsystem connectors.

The full address for a resource is the ordered list of key/value pairs that lead from the root of the tree to the resource. Typical notation is to separate the elements in the address with a '/' and to separate the key and the value with an '=':

  • /subsystem=web/connector=http
  • /subsystem=messaging/jms-queue=testQueue
  • /interface=public

When using the HTTP API, a '/' is used to separate the key and the value instead of an '=':

  • http://localhost:9990/management/subsystem/web/connector/http
  • http://localhost:9990/management/subsystem/messaging/jms-queue/testQueue
  • http://localhost:9990/management/interface/public

Operations

Querying or modifying the state of a resource is done via an operation. An operation has the following characteristics:

  • A string name
  • Zero or more named parameters. Each parameter has a string name, and a value of type org.jboss.dmr.ModelNode (or, when invoked via the CLI, the text representation of a ModelNode; when invoked via the HTTP API, the JSON representation of a ModelNode.) Parameters may be optional.
  • A return value, which will be of type org.jboss.dmr.ModelNode (or, when invoked via the CLI, the text representation of a ModelNode; when invoked via the HTTP API, the JSON representation of a ModelNode.)

Every resource except the root resource will have an add operation and should have a remove operation ("should" because in AS 7.0 many do not.) The parameters for the add operation vary depending on the resource. The remove operation has no parameters.

There are also a number of "global" operations that apply to all resources. See Global operations for full details.

The operations a resource supports can themselves be determined by invoking an operation: the read-operation-names operation. Once the name of an operation is known, details about its parameters and return value can be determined by invoking the read-operation-description operation. For example, to learn the names of the operations exposed by the root resource for a standalone server, and then learn the full details of one of them, via the CLI one would:

See Descriptions below for more on how to learn about the operations a resource exposes.

Attributes

Management resources expose information about their state as attributes. Attributes have string name, and a value of type org.jboss.dmr.ModelNode (or: for the CLI, the text representation of a ModelNode; for HTTP API, the JSON representation of a ModelNode.)

Attributes can either be read-only or read-write. Reading and writing attribute values is done via the global read-attribute and write-attribute operations.

The read-attribute operation takes a single parameter "name" whose value is a the name of the attribute. For example, to read the "port" attribute of a socket-binding resource via the CLI:

If an attribute is writable, the write-attribute operation is used to mutate its state. The operation takes two parameters:

  • name – the name of the attribute
  • value – the value of the attribute

For example, to read the "port" attribute of a socket-binding resource via the CLI:

Attributes can have one of two possible storage types:

  • CONFIGURATION – means the value of the attribute is stored in the persistent configuration; i.e. in the domain.xml, host.xml or standalone.xml file from which the resource's configuration was read.
  • RUNTIME – the attribute value is only available from a running server; the value is not stored in the persistent configuration. A metric (e.g. number of requests serviced) is a typical example of a RUNTIME attribute.

The values of all of the attributes a resource exposes can be obtained via the read-resource operation, with the "include-runtime" parameter set to "true". For example, from the CLI:

Omit the "include-runtime" parameter (or set it to "false") to limit output to those attributes whose values are stored in the persistent configuration:

See Descriptions below for how to learn more about the attributes a particular resource exposes.

Children

Management resources may support child resources. The types of children a resource supports (e.g. connector for the web subsystem resource) can be obtained by querying the resource's description (see Descriptions below) or by invoking the read-children-types operation. Once you know the legal child types, you can query the names of all children of a given type by using the global read-children-names operation. The operation takes a single parameter "child-type" whose value is the type. For example, a resource representing a socket binding group has children. To find the type of those children and the names of resources of that type via the CLI one could:

Descriptions

All resources expose metadata that describes their attributes, operations and child types. This metadata is itself obtained by invoking one or more of the global operations each resource supports. We showed examples of the read-operation-names, read-operation-description, read-children-types and read-children-names operations above.

The read-resource-description operation can be used to find the details of the attributes and child types associated with a resource. For example, using the CLI:

Note the "operations" => {} in the output above. If the command had included the operations parameter (i.e. /socket-binding-group=standard-sockets:read-resource-description(operations=true)) the output would have included the description of each operation supported by the resource.

See the Global operations section for details on other parameters supported by the read-resource-description operation and all the other globally available operations.

Comparison to JMX MBeans

JBoss AS management resources are conceptually quite similar to Open MBeans. They have the following primary differences:

  • JBoss AS management resources are organized in a tree structure. The order of the key value pairs in a resource's address is significant, as it defines the resource's position in the tree. The order of the key properties in a JMX ObjectName is not significant.
  • In an Open MBean attribute values, operation parameter values and operation return values must either be one of the simple JDK types (String, Boolean, Integer, etc) or implement either the javax.management.openmbean.CompositeData interface or the javax.management.openmbean.TabularData interface. JBoss AS management resource attribute values, operation parameter values and operation return values are all of type org.jboss.dmr.ModelNode.

Basic structure of the management resource trees

As noted above, management resources are organized in a tree structure. The structure of the tree depends on whether you are running a standalone server or a managed domain.

Standalone server

The structure of the managed resource tree is quite close to the structure of the standalone.xml configuration file.

  • The root resource
    • extension – extensions installed in the server
    • path – paths available on the server
    • system-property – system properties set as part of the configuration (i.e. not on the command line)
    • core-service=management – the server's core management services
    • core-service=service-container – resource for the JBoss MSC ServiceContainer that's at the heart of the AS
    • subsystem – the subsystems installed on the server. The bulk of the management model will be children of type subsystem
    • interface – interface configurations
    • socket-binding-group – the central resource for the server's socket bindings
      • socket-binding – individual socket binding configurations
    • deployment – available deployments on the server

Managed domain

In a managed domain, the structure of the managed resource tree spans the entire domain, covering both the domain wide configuration (e.g. what's in domain.xml, the host specific configuration for each host (e.g. what's in host.xml, and the resources exposed by each running application server. The Host Controller processes in a managed domain provide access to all or part of the overall resource tree. How much is available depends on whether the management client is interacting with the Host Controller that is acting as the master Domain Controller. If the Host Controller is the master Domain Controller, then the section of the tree for each host is available. If the Host Controller is a slave to a remote Domain Controller, then only the portion of the tree associated with that host is available.

  • The root resource for the entire domain. The persistent configuration associated with this resource and its children, except for those of type host, is persisted in the domain.xml file on the Domain Controller.
    • extension – extensions available in the domain
    • path – paths available on across the domain
    • system-property – system properties set as part of the configuration (i.e. not on the command line) and available across the domain
    • profile – sets of subsystem configurations that can be assigned to server groups
      • subsystem – configuration of subsystems that are part of the profile
    • interface – interface configurations
    • socket-binding-group – sets of socket bindings configurations that can be applied to server groups
      • socket-binding – individual socket binding configurations
    • deployment – deployments available for assignment to server groups
    • server-group – server group configurations
    • host – the individual Host Controllers. Each child of this type represents the root resource for a particular host. The persistent configuration associated with one of these resources or its children is persisted in the host's host.xml file.
      • path – paths available on each server on the host
      • system-property – system properties to set on each server on the host
      • core-service=management – the Host Controller's core management services
      • interface – interface configurations that apply to the Host Controller or servers on the host
      • jvm – JVM configurations that can be applied when launching servers
      • server-config – configuration describing how the Host Controller should launch a server; what server group configuration to use, and any server-specific overrides of items specified in other resources
      • server – the root resource for a running server. Resources from here and below are not directly persisted; the domain-wide and host level resources contain the persistent configuration that drives a server
        • extension – extensions installed in the server
        • path – paths available on the server
        • system-property – system properties set as part of the configuration (i.e. not on the command line)
        • core-service=management – the server's core management services
        • core-service=service-container – resource for the JBoss MSC ServiceContainer that's at the heart of the AS
        • subsystem – the subsystems installed on the server. The bulk of the management model will be children of type subsystem
        • interface – interface configurations
        • socket-binding-group – the central resource for the server's socket bindings
          • socket-binding – individual socket binding configurations
        • deployment – available deployments on the server
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jun 26, 2012

    I think this document should at least briefly mention the process controller and make clear that the host controller is not the parent of a server but a child of the process controller the same way the servers are.