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

IPv4 versus IPv6

JBoss AS7 supports the use of both IPv4 and IPv6 addresses. By default, AS7 is configured for use in an IPv4 network and so if you are running AS7 in an IPv4 network, no changes are required. If you need to run AS7 in an IPv6 network, the changes required are minimal and involve changing the JVM stack and address preferences, and adjusting any interface IP address values specified in the configuration (standalone.xml or domain.xml).

Stack and address preference

The system properties java.net.preferIPv4Stack and java.net.preferIPv6Addresses are used to configure the JVM for use with IPv4 or IPv6 addresses. With AS7, in order to run using IPv4 addresses, we need to specify java.net.preferIPv4Stack=true; in order to run the AS7 with IPv6 addresses, we need to specify java.net.preferIPv4Stack=false (the JVM default) and java.net.preferIPv6Addresses=true. The latter ensures that any hostname to IP address conversions always return IPv6 address variants.

These system properties are conveniently set by the JAVA_OPTS environment variable, defined in the standalone.conf (or domain.conf) file. For example, to change the IP stack preference from its default of IPv4 to IPv6, edit the standalone.conf (or domain.conf) file and change its default IPv4 setting:

to an IPv6 suitable setting:

IP address literals

To change the IP address literals referenced in standalone.xml (or domain.xml), first visit the interface declarations and ensure that valid IPv6 addresses are being used as interface values. For example, to change the default configuration in which the loopback interface is used as the primary interface, change from the IPv4 loopback address:

to the IPv6 loopback address:

Note that when embedding IPv6 address literals in the substitution expression, square brackets surrounding the IP address literal are used to avoid ambiguity. This follows the convention for the use of IPv6 literals in URLs.

Over and above making such changes for the interface definitions, you should also check the rest of your configuration file and adjust IP address literals from IPv4 to IPv6 as required.

Configure Security Realms

Within JBoss AS 7 we make use of security realms to secure access to the management interfaces, these same realms are used to secure inbound access as exposed by JBoss Remoting such as remote JNDI and EJB access, the realms are also used to define an identity for the server - this identity can be used for both inbound connections to the server and outbound connections being established by the server.

General Structure

The general structure of a management realm definition is: -

  • plug-ins - This is an optional element that is used to define modules what will be searched for security realm PlugInProviders to extend the capabilities of the security realms.
  • server-identities - An optional element to define the identity of the server as visible to the outside world, this applies to both inbound connection to a resource secured by the realm and to outbound connections also associated with the realm.

One example is the SSL identity of the server, for inbound connections this will control the identity of the server as the SSL connection is established, for outbound connections this same identity can be used where CLIENT-CERT style authentication is being performed.

A second example is where the server is establishing an outbound connection that requires username / password authentication - this element can be used to define that password.

  • authentication - This is probably the most important element that will be used within a security realm definition and mostly applies to inbound connections to the server, this element defines which backing stores will be used to provide the verification of the inbound connection.

This element is optional as there are some scenarios where it will not be required such as if a realm is being defined for an outbound connection using a username and password.

  • authorization - This is the final optional element and is used to define how roles are loaded for an authenticated identity. At the moment this is more applicable for realms used for access to EE deployments such as web applications or EJBs but this will also become relevant as we add role based authorization checks to the management model.

Enabling a Realm

After a realm has been defined it needs to be associated with an inbound or outbound connection for it to be used, the following are some examples where these associations are used within the AS7 configuration.

Inbound Connections

Management Interfaces

Either within the standalone.xml or host.xml configurations the security realms can be associated with the management interfaces as follows: -

If the security-realm attribute is omitted or removed from the interface definition it means that access to that interface will be unsecured

By default we do bind these interfaces to the loopback address so that the interfaces are not accessible remotely out of the box, however do be aware that if these interfaces are then unsecured any other local user will be able to control and administer the AS7 installation.
Also do note that the security-realm attribute is defined on each interface independently, this means that you could define a different security realm for each - this may be applicable if say you want the administrators to only access over the HTTP interface and leave only local users to access the native interface.
Remoting Subsystem

The Remoting subsystem exposes a connector to allow for inbound comunications with JNDI and the EJB subsystem by default we associate the ApplicationRealm with this connection.

Outbound Connections

Remoting Subsystem

Outbound connections can also be defined within the Remoting subsystem, these are typically used for remote EJB invocations from one AS server to another, in this scenario the security realm is used to obtain the server identity either it's password for X.509 certificate and possibly a trust store to verify the certificate of the remote host.

Even if the referenced realm contains username and password authentication configuration the client side of the connection will NOT use this to verify the remote server.
The security realm is only used to obtain the password for this example, as you can see here the username is specified separately.
Slave Domain Controller

When running in domain mode slave domain controllers need to establish a connection to the native interface of the master domain controller so these also need a realm for the identity of the slave.

By default when a slave domain controller authenticates against the master domain controller it uses the name of it's host controller as it's username, if you want to override the username used for authentication a username attribute can be added to the <remote /> element.

Authentication

One of the primary functions of the security realms is to define the user stores that will be used to verify the identity of inbound connections, the actual approach taken at the transport level is based on the capabilities of these backing store definitions. The security realms are used to secure inbound connections for both the http management interface and for inbound remoting connections for both the native management interface and to access other services exposed over remoting - because of this there are some small differences between how the realm is used for each of these.

At the transport level we support the following authentication mechanisms.

HTTP Remoting (SASL)
None Anonymous
N/A JBoss Local User
Digest Digest
Basic Plain
Client Cert Client Cert

The most notable are the first two in this list as they need some additional explanation - the final 3 are fairly standard mechanisms.

If either the http interface, the native interface or a remoting connection are difined without a security realm reference then they are effectively unsecured, in the case of the http interface this means that no authentication will be performed on the incoming connection - for the remoting connections however we make use of SASL so require at least one authentication mechanism so make use of the anonymous mechanism to allow a user in without requiring a validated authentication process.

The next mechanism 'JBoss Local User' is specific to the remoting connections - as we ship AS 7.1 secured by default we wanted a way to allow users to connect to their own AS installation after it is started without mandating that they define a user with a password - to accomplish this we have added the 'JBoss Local User' mechanism. This mechanism makes the use of tokens exchanged on the filesystem to prove that the client is local to the AS installation and has the appropriate file permissions to read a token written by the AS to file. As this mechanism is dependent on both server and client implementation details it is only supported for the remoting connections and not the http connections - at some point we may review if we can add support for this to the http interface but we would need to explore the options available with the commony used web browsers that are used to communicate with the http interface.

The Digest mechanism is simply the HTTP Digest / SASL Digest mechanism that authenticates the user by making use of md5 hashed including nonces to avoid sending passwords in plain text over the network - this is the preferred mechanism for username / password authentication.

The HTTP Basic / SASL Plain mechanism is made available for times that Digest can not be used but effectively this means that the users password will be sent over the network in the clear unless SSL is enabled.

The final mechanism Client-Cert allows X.509 certificates to be used to verify the identity of the remote client.

One point bearing in mind is that it is possible that an association with a realm can mean that a single incoming connection has the ability to choose between one or more authentication mechanisms. As an example it is possible that an incoming remoting connection could choose between 'Client Cert', A username password mechanism or 'JBoss Local User' for authentication - this would allow say a local user to use the local mechanism, a remote user to supply their username and password whilst a remote script could make a call and authenticate using a certificate.

Authorization

The actual security realms are not involved in any authorization decisions however they can be configured to load a users roles which will subsequently be used to make authorization decisions - when references to authorization are seen in the context of security realms it is this loading of roles that is being referred to.

For the loading of roles the process is split out to occur after the authentication step so after a user has been authenticated a second step will occur to load the roles based on the username they used to authenticate with.

Out Of The Box Configuration

Before describing the complete set of configuration options available within the realms we will look at the default configuration as for most users that is going to be the starting point before customising further.

The examples here are taken from the standalone configuration however the descriptions are equally applicable to domain mode, one point worth noting is that all security realms defined in the host.xml are available to be referenced within the domain configuration for the servers running on that host controller.

Management Realm

The realm ManagementRealm is the simplest realm within the default configuration, this realm simply enables two authentication mechanisms, the local mechanism and username/password authentication which will be using Digest authentication.

  • local

When using the local mechanism it is optional for remote clients to send a username to the server, this configuration specifies that where clients do not send a username it will be assumed that the clients username is $local - the <local /> element can also be configured to allow other usernames to be specified by remote clients however for the default configuration this is not enabled so is not supported.

  • properties

For username / password authentication the users details will be loaded from the file mgmt-users.properties which is located in {jboss.home}/standalone/configuration or {jboss.home}/domain/configuration depending on the running mode of the server.

Each user is represented on their own line and the format of each line is username=HASH where HASH is a pre-prepared hash of the users password along with their username and the name of the realm which in this case is ManagementRealm.

You do not need to worry about generating the entries within the properties file as we provide a utility add-user.sh or add-user.bat to add the users, this utility is described in more detail below.
By pre-hashing the passwords in the properties file it does mean that if the user has used the same password on different realms then the contents of the file falling into the wrong hands does not nescesarily mean all accounts are compromised. HOWEVER the contents of the files do still need to be protected as they can be used to access any server where the realm name is the same and the user has the same username and password pair.

Application Realm

The realm ApplicationRealm is a slightly more complex realm as this is used for both

Authentication

The authentication configuration is very similar to the ManagementRealm in that it enabled both the local mechanism and a username/password based Digest mechanism.

  • local

The local configuration is similar to the ManagementRealm in that where the remote user does not supply a username it will be assumed that the username is $local, however in addition to this there is now an allowed-users attribute with a value of '*' - this means that the remote user can specify any username and it will be accepted over the local mechanism provided that the local verification is a success.

To restrict the usernames that can be specified by the remote user a comma separated list of usernames can be specified instead within the allowed-users attribute.
  • properties

The properties definition works in exactly the same way as the definition for ManagementRealm except now the properties file is called application-users.properties.

Authorization

The contents of the Authorization element are specific to the ApplicationRealm, in this case a properties file is used to load a users roles.

The properties file is called application-roles.properties and is located in {jboss.home}/standalone/configuration or {jboss.home}/domain/configuration depending on the running mode of the server. The format of this file is username=ROLES where ROLES is a comma separated list of the users roles.

As the loading of a users roles is a second step this is where it may be desirable to restrict which users can use the local mechanism so that some users still require username and password authentication for their roles to be loaded.

other security domain

When applications are deployed to the application server they are associated with a security domain within the security subsystem, the other security domain is provided to work with the ApplicationRealm, this domain is defined with a pair of login modules Remoting and RealmDirect.

  • Remoting

The Remoting login module is used to check if the request currently being authenticated is a request received over a Remoting connection, if so the identity that was created during the authentication process is used and associated with the current request.

If the request did not arrive over a Remoting connection this module does nothing and allows the JAAS based login to continue to the next module.

  • RealmDirect

The RealmDirect login module makes use of a security realm to authenticate the current request if that did not occur in the Remoting login module and then use the realm to load the users roles, by default this login module assumes the realm to use is called ApplicationRealm although other names can be overridden.

The advantage of this approach is that all of the backing store configuration can be left within the realm with the security domain just delegating to the realm.

add-user.sh

For use with the default configuration we supply a utility add-user which can be used to manage the properties files for the default realms used to store the users and their roles.

The add-user utility can be used to manage both the users in the ManagementRealm and the users in the ApplicationRealm, changes made apply to the properties file used both for domain mode and standalone mode.

After you have installed your application server and decided if you are going to run in standalone mode or domain mode you can delete the parent folder for the mode you are not using, the add-user utility will then only be managing the properties file for the mode in use.

The add-user utility is a command line utility however it can be run in both interactive and non-interactive mode. Depending on your platform the script to run the add-user utility is either add-user.sh or add-user.bat which can be found in {jboss.home}/bin.

This guide now contains a couple of examples of this utility in use to accomplish the most common tasks.

Adding a User

Adding users to the properties files is the primary purpose of this utility.

The server caches the contents of the properties files in memory, however the server does check the modified time of the properties files on each authentication request and re-load if the time has been updated - this means all changes made by this utility are immediately applied to any running server.
A Management User
The default name of the realm for management users is ManagementRealm, when the utility prompts for the realm name just accept the default unless you have switched to a different realm.
Interactive Mode

Here we have added a new Management User called adminUser, as you can see some of the questions offer default responses so you can just press enter without repeating the default value.

For now just answer n or no to the final question, adding users to be used by processes is described in more detail in the domain management chapter.

Non-Interactive Mode

To add a user in non-interactive mode the command ./add-user.sh {username} {password} can be used.

If you add users using this approach there is a risk that any other user that can view the list of running process may see the arguments including the password of the user being added, there is also the risk that the username / password combination will be cached in the history file of the shell you are currently using.
An Application User

When adding application users in addition to adding the user with their pre-hashed password it is also now possible to define the roles of the user.

Interactive Mode

Here a new user called appUser has been added, in this case a comma separated list of roles has also been specified.

As with adding a management user just answer n or no to the final question until you know you are adding a user that will be establishing a connection from one server to another.

Non-Interactive Mode

To add an application user non-interactively use the command ./add-user.sh -a {username} {password}.

Non-interactive mode does not support defining a list of users, to associate a user with a set of roles you will need to manually edit the application-roles.properties file by hand.

Updating a User

Within the add-user utility it is also possible to update existing users, in interactive mode you will be prompted to confirm if this is your intention.

A Management User
Interactive Mode

Non-Interactive Mode

In non-interactive mode if a user already exists the update is automatic with no confirmation prompt.

An Application User
Interactive Mode

On updating a user with roles you will need to re-enter the list of roles assigned to the user.
Non-Interactive Mode

In non-interactive mode if a user already exists the update is automatic with no confirmation prompt.

Community Contributions

There are still a few features to add to the add-user utility such as removing users or adding application users with roles in non-interactive mode, if you are interested in contributing to JBoss AS development the add-user utility is a good place to start as it is a stand alone utility, however it is a part of the AS build so you can become familiar with the AS development processes without needing to delve straight into the internals of the application server.

JMX

When configuring the security realms remote access to the servers MBeanServer needs a special mention, when running in standalone mode the following is the default configuration: -

With this configuration remote access to JMX is provided over the native management interface, this is secured using the realm ManagementRealm, this means that any user that can connect to the native interface can also use this interface to access the MBeanServer - to disable this just remove the <remoting-connector /> element.

In domain mode it is slightly more complicates as the native interface is exposed by the host controller process however each application server is running in it's own process so by default remote access to JMX is disabled.

To enable remote access to JMX uncomment the <remoting-connector /> element however be aware that this will make the MBeanServer accessible over the same Remoting connector used for remote JNDI and EJB access - this means that any user that can authenticate against the realm ApplicationRealm will be able to access the MBeanServer.

The following Jira issue is currently outstanding to allow access to the individual MBeanServers by proxying through the host controllers native interface AS7-4009, if this is a feature you would use please add your vote to the issue.

Detailed Configuration

This section of the documentation describes the various configuration options when defining realms, plug-ins are a slightly special case so the configuration options for plug-ins is within it's own section.

Within a security realm definition there are four optional elements <plug-ins />, <server-identities />, <authentication />, and <authorization />, as mentioned above plug-ins is defined within it's own section below so we will begin by looking at the <server-identities /> element.

<server-identities />

The server identities section of a realm definition is used to define how a server appears to the outside world, currently this element can be used to configure a password to be used when establishing a remote outbound connection and also how to load a X.509 key which can be used for both inbound and outbound SSL connections.

<ssl />

  • protocol - By default this is set to TLS and in general does not need to be set.

The SSL element then contains the nested <keystore /> element, this is used to define how to load the key from the file based (JKS) keystore.

  • path (mandatory) - This is the path to the keystore, this can be an absolute path or relative to the next attribute.
  • relative-to (optional) - The name of a service representing a path the keystore is relative to.
  • keystore-password (mandatory) - The password required to open the keystore.
  • alias (optional) - The alias of the entry to use from the keystore - for a keystore with multiple entries in practice the first usable entry is used but this should not be relied on and the alias should be set to guarantee which entry is used.
  • key-password (optional) - The password to load the key entry, if omitted the keystore-password will be used instead.
If you see the error UnrecoverableKeyException: Cannot recover key the most likely cause that you need to specify a key-password and possible even an alias as well to ensure only one key is loaded.

<secret />

  • value (mandatory) - The password to use for outbound connections encoded as Base64, this field also supports a vault expression should stronger protection be required.
The username for the outbound connection is specified at the point the outbound connection is defined.

<authentication />

The authentication element is predominantly used to configure the authentication that is performed on an inbound connection, however there is one exception and that is if a trust store is defined - on negotiating an outbound SSL connection the trust store will be used to verify the remote server.

An authentication definition can have zero or one <truststore />, it can also have zero or one <local /> and it can also have one of <jaas />, <ldap />, <properties />, <users />, and <plug-in /> i.e. the local mechanism and a truststore for certificate verification can be independent switched on and off and a single username / password store can be defined.

<truststore />

This element is used to define how to load a key store file that can be used as the trust store within the SSLContext we create internally, the store is then used to verify the certificates of the remote side of the connection be that inbound or outbound.

  • path (mandatory) - This is the path to the keystore, this can be an absolute path or relative to the next attribute.
  • relative-to (optional) - The name of a service representing a path the keystore is relative to.
  • keystore-password (mandatory) - The password required to open the keystore.
Although this is a definition of a trust store the attribute for the password is keystore-password, this is because the underlying file being opened is still a key store.
Due to the AS7-4698 bug in 7.1.1 use password instead of keystore-password attribute in truststore element. This bug was fixed in 7.1.2.

<local />

This element switches on the local authentication mechanism that allows clients to the server to verify that they are local to the server, at the protocol level it is optional for the remote client to send a user name in the authentication response.

  • default-user (optional) - If the client does not pass in a username this is the assumed username, this value is also automatically added to the list of allowed-users.
  • allowed-users (optional) - This attribute is used to specify a comma separated list of users allowed to authenticate using the local mechanism, alternatively '*' can be specified to allow any username to be specified.

<jaas />

The jaas element is used to enable username and password based authentication where the supplied username and password are verified by making use of a configured jaas domain.

  • name (mandatory) - The name of the jaas domain to use to verify the supplied username and password.
As JAAS authentication works by taking a username and password and verifying these the use of this element means that at the transport level authentication will be forced to send the password in plain text, any interception of the messages exchanged between the client and server without SSL enabled will reveal the users password.

<ldap />

The ldap element is used to define how LDAP searches will be used to authenticate a user, this works by first connecting to LDAP and performing a search using the supplied user name to identity the distinguished name of the user and then a subsequent connection is made to the server using the password supplied by the user - if this second connection is a success then authentication succeeds.

Due to the verification approach used this configuration causes the authentication mechanisms selected for the protocol to cause the password to be sent from the client in plain text, the following Jira issue is to investigating proxying a Digest authentication with the LDAP server so no plain text password is needed AS7-4195.
  • connection (mandatory) - The name of the connection to use to connect to LDAP.
  • base-dn (mandatory) - The distinguished name of the context to use to begin the search from.
  • recursive (optional) - Should the filter be executed recursively? Defaults to false.
  • user-dn (optional) - After the user has been found specifies which attribute to read for the users distinguished name, defaults to 'dn'.

Within the ldap element only one of <username-filter /> or <advanced-filter /> can be specified.

<username-filter />

This element is used for a simple filter to match the username specified by the remote user against a single attribute, as an example with Active Directory the match is most likely to be against the 'sAMAccountName' attribute.

  • attribute (mandatory) - The name of the field to match the users supplied username against.
<advanced-filter />

This element is used where a more advanced filter is required, one example use of this filter is to exclude certain matches by specifying some additional criteria for the filter.

  • filter (mandatory) - The filter to execute to locate the user, this filter should contain '{0}' as a place holder for the username supplied by the user authenticating.

<properties />

The properties element is used to reference a properties file to load to read a users password or pre-prepared digest for the authentication process.

  • path (mandatory) - The path to the properties file, either absolute or relative to the path referenced by the relative-to attribute.
  • relative-to (optional) - The name of a path service that the defined path will be relative to.
  • plain-text (optional) - Setting to specify if the passwords are stored as plain text within the properties file, defaults to false.
By default the properties files are expected to store a pre-prepared hash of the users password in the form HEX( MD5( username ':' realm ':' password))

<users />

This is a very simple store of a username and password that stores both of these within the domain model, this is only really provided for the provision of simple examples.

  • username (mandatory) - A users username.

The <password/> element is then used to define the password for the user.

<authorization />

The authorization element is used to define how a users roles can be loaded after the authentication process completes, these roles may then be used for subsequent authorization decisions based on the service being accessed. At the moment only a properties file approach or a custom plug-in are supported - support for loading roles from LDAP or from a database are planned for a subsequent release.

<properties />

The format of the properties file is username={ROLES} where {ROLES} is a comma separated list of the users roles.

  • path (mandatory) - The path to the properties file, either absolute or relative to the path referenced by the relative-to attribute.
  • relative-to (optional) - The name of a path service that the defined path will be relative to.

<outbound-connection />

Strictly speaking these are not a part of the security realm definition, however at the moment they are only used by security realms so the definition of outbound connection is described here.

<ldap />

At the moment we only support outbound connections to ldap servers for the authentication process - this will later be expanded when we add support for database based authentication.

The outbound connections are defined in this section and then referenced by name from the configuration that makes use of them.

  • name (mandatory) - The unique name used to reference this connection.
  • url (mandatory) - The URL use to establish the LDAP connection.
  • search-dn (mandatory) - The distinguished name of the user to authenticate as to perform the searches.
  • search-credential (mandatory) - The password required to connect to LDAP as the search-dn.
  • initial-context-factory (optional) - Allows overriding the initial context factory, defaults to 'com.sun.jndi.ldap.LdapCtxFactory'

Plug Ins

Within JBoss AS7 for communication with the management interfaces and for other services exposed using Remoting where username / password authentication is used the use of Digest authentication is preferred over the use of HTTP Basic or SASL Plain so that we can avoid the sending of password in the clear over the network. For validation of the digests to work on the server we either need to be able to retrieve a users plain text password or we need to be able to obtain a ready prepared hash of their password along with the username and realm.

Previously to allow the addition of custom user stores we have added an option to the realms to call out to a JAAS domain to validate a users username and password, the problem with this approach is that to call JAAS we need the remote user to send in their plain text username and password so that a JAAS LoginModule can perform the validation, this forces us down to use either the HTTP Basic authentication mechanism or the SASL Plain mechanism depending on the transport used which is undesirable as we can not longer use Digest.

To overcome this we now support plugging in custom user stores to support loading a users password, hash and roles from a custom store to allow different stores to be implemented without forcing the authentication back to plain text variant, this article describes the requirements for a plug in and shows a simple example plug-in for use with AS7.

When implementing a plug in there are two steps to the authentication process, the first step is to load the users identity and credential from the relevent store - this is then used to verify the user attempting to connect is valid. After the remote user is validated we then load the users roles in a second step. For this reason the support for plug-ins is split into the two stages, when providing a plug-in either of these two steps can be implemented but there is no requirement to implement the other side.

When implementing a plug-in the following interfaces are the bare minimum that need to be implemented so depending on if a plug-in to load a users identity or a plug-in to load a users roles is being implemented you will be implementing one of these interfaces.

Note - All classes and interfaces of the SPI to be implemented are in the 'org.jboss.as.domain.management.plugin' package which is a part of the 'org.jboss.as.domain-management' module but for simplicity for the rest of this section only the short names will be shown.

AuthenticationPlugIn

To implement an AuthenticationPlugIn the following interface needs to be implemened: -

During the authenication process this method will be called with the user name supplied by the remote user and the name of the realm they are authenticating against, this method call represents that an authentication attempt is occurring but it is the Identity instance that is returned that will be used for the actual authentication to verify the remote user.

The Identity interface is also an interface you will implement: -

Additional information can be contained within the Identity implementation although it will not currently be used, the key piece of information here is the Credential that will be returned - this needs to be one of the following: -

PasswordCredential

The PasswordCredential is already implemented so use this class if you have the plain text password of the remote user, by using this the secured interfaces will be able to continue using the Digest mechanism for authentication.

DigestCredential

This class is also already implemented and should be returned if instead of the plain text password you already have a pre-prepared hash of the username, realm and password.

ValidatePasswordCredential

This is a special Credential type to use when it is not possible to obtain either a plain text representation of the password or a pre-prepared hash - this is an interface as you will need to provide an implementation to verify a supplied password. The down side of using this type of Credential is that the authentication mechanism used at the transport level will need to drop down from Digest to either HTTP Basic or SASL Plain which will now mean that the remote client is sending their credential across the network in the clear.

If you use this type of credential be sure to force the mechanism choice to Plain as described in the configuration section below.

AuthorizationPlugIn

If you are implementing a custom mechanism to load a users roles you need to implement the AuthorizationPlugIn

As with the AuthenticationPlugIn this has a single method that takes a users userName and realm - the return type is an array of Strings with each entry representing a role the user is a member of.

PlugInConfigurationSupport

In addition to the specific interfaces above there is an additional interface that a plug-in can implement to recieve configuration information before the plug-in is used and also to recieve a Map instance that can be used to share state between the plug-in instance used for the authentication step of the call and the plug-in instance used for the authorization step.

Installing and Configuring a Plug-In

The next step of this article describes the steps to implement a plug-in provider and how to make it available within AS7 and how to configure it. Example configuration and an example implementation are shown to illustrate this.

The following is an example security realm definition which will be used to illustrate this: -

Before looking closely at the packaging and configuration there is one more interface to implement and that is the PlugInProvider interface, that interface is responsible for making PlugIn instances available at runtime to handle the requests.

PlugInProvider

These methods are called with the name that is supplied in the plug-in elements that are contained within the authentication and authorization elements of the configuration, based on the sample configuration above the loadAuthenticationPlugIn method will be called with a parameter of 'Sample' and the loadAuthorizationPlugIn method will be called with a parameter of 'Delegate'.

Multiple plug-in providers may be available to the application server so if a PlugInProvider implementation does not recognise a name then it should just return null and the server will continue searching the other providers. If a PlugInProvider does recognise a name but fails to instantiate the PlugIn then a RuntimeException can be thrown to indicate the failure.

As a server could have many providers registered it is recommended that a naming convention including some form of hierarchy is used e.g. use package style names to avoid conflicts.

For the example the implementation is as follows: -

The load methods are called for each authentication attempt but it will be an implementation detail of the provider if it decides to return a new instance of the provider each time - in this scenario as we also use configuration and shared state then new instances of the implementations make sense.

To load the provider use a ServiceLoader so within the META-INF/services folder of the jar this project adds a file called 'org.jboss.as.domain.management.plugin.PlugInProvider' - this contains a single entry which is the fully qualified class name of the PlugInProvider implementation class.

Package as a Module

To make the PlugInProvider available to the application it is bundled as a module and added to the modules already shipped with AS7.

To add as a module we first need a module.xml: -

The interfaces being implemented are in the 'org.jboss.as.domain-management' module so a dependency on that module is defined, this module.xml is then placed in the '{jboss.home}/modules/org/jboss/as/sample/plugin/main'.

The compiled classed and META-INF/services as described above are assmbled into a jar called SamplePlugIn.jar and also placed into this folder.

Looking back at the sample configuration at the top of the realm definition the following element was added: -

This element is used to list the modules that should be searched for plug-ins. As plug-ins are loaded during the server start up this search is a lazy search so don't expect a definition to a non existant module or to a module that does not contain a plug-in to report an error.

The AuthenticationPlugIn

The example AuthenticationPlugIn is implemented as: -

As you can see from this implementation there is also an additional class being extended AbstractPlugIn - that is simply an abstract class that implements the AuthenticationPlugIn, AuthorizationPlugIn, and PlugInConfigurationSupport interfaces already. The properties that were defined in the configuration are passed in as a Map and importantly for this sample the plug-in adds itself to the shared state map.

The AuthorizationPlugIn

The example implementation of the authentication plug in is as follows: -

This plug-in illustrates how two plug-ins can work together, by the AuthenticationPlugIn placing itself in the shared state map it is possible for the authorization plug-in to make use of it for the loadRoles implementation.

Another option to consider to achieve similar behaviour could be to provide an Identity implementation that also contains the roles and place this in the shared state map - the AuthorizationPlugIn can retrieve this and return the roles.

Forcing Plain Text Authentication

As mentioned earlier in this article if the ValidatePasswordCredential is going to be used then the authentication used at the transport level needs to be forced from Digest authentication to plain text authentication, this can be achieved by adding a mechanism attribute to the plug-in definition within the authentication element i.e.

Example Configurations

This section of the document contains a couple of examples for the most common scenarios likely to be used with the security realms, please feel free to raise Jira issues requesting additional scenarios or if you have configured something not covered here please feel free to add your own examples - this document is editable after all

At the moment these examples are making use of the 'ManagementRealm' however the same can apply to the 'ApplicationRealm' or any custom realm you create for yourselves.

LDAP Authentication

The following example demonstrates an example configuration making use of Active Directory to verify the users username and password.

For simplicity the <local/> configuration has been removed from this example, however there it is fine to leave that in place for local authentication to remain possible.

Enable SSL

The first step is the creation of the key, by default this is going to be used for both the native management interface and the http management interface - to create the key we can use the keyTool, the following example will create a key valid for one year.

Open a terminal window in the folder {jboss.home}/standalone/configuration and enter the following command: -

keytool -genkey -alias server -keyalg RSA -keystore server.keystore -validity 365

In this example I choose 'keystore_password'.

Of all of the questions asked this is the most important and should match the host name that will be entered into the web browser to connect to the admin console.

Answer the remaining questions as you see fit and at the end for the purpose of this example I set the key password to 'key_password'.

The following example shows how this newly created keystore will be referenced to enable SSL.

The contents of the <authentication /> have not been changed in this example so authentication still occurs using either the local mechanism or username/password authentication using Digest.

Add Client-Cert to SSL

To enable Client-Cert style authentication we just now need to add a <truststore /> element to the <authentication /> element referencing a trust store that has had the certificates or trusted clients imported.

In this scenario if Client-Cert authentication does not occur clients can fall back to use either the local mechanism or username/password authentication. To make Client-Cert based authentication mandatory just remove the <local /> and <properties /> elements.

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, execute the $JBOSS_HOME/bin/domain.sh script. To start up a standalone server, execute the $JBOSS_HOME/bin/standalone.sh. With no arguments, the default configuration is used. You can override the default configuration by providing arguments on the command line, or in your calling script.

System properties

The standalone and the managed domain modes each use a default configuration which expects various files and writable directories to exist in standard locations. Each of these standard locations is associated with a system property, which has a default value. To override a system property, pass its new value using the standard jvm -Dkey=value options:

This command starts up a standalone server instance using a non-standard AS home directory and a custom configuration directory. For specific information about system properties, refer to the definitions below.

Instead of passing the parameters directly, you can put them into a properties file, and pass the properties file to the script, as in the two examples below.

The syntax for passing in parameters and properties files is the same regardless of whether you are running the domain.sh, standalone.sh, or the Microsoft Windows scriptsdomain.bat or standalone.bat.

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

Standalone

Property name Usage Default value
java.ext.dirs The 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/servers

Other command line parameters

The first acceptable format for command line arguments to the JBoss AS launch scripts is

For example:

If the parameter name is a single character, it is prefixed by a single '-' instead of two. Some parameters have both a long and short option.

For example:

For some command line arguments frequently used in previous major releases of JBoss AS, replacing the "=" in the above examples with a space is supported, for compatibility.

If possible, use the -x=value syntax. New parameters will always support this syntax.

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
-c
jboss.server.config.dir/standalone.xml A relative path which is interpreted to be relative to jboss.server.config.dir.

Managed Domain

Name Default if absent Value
--domain-config
-c
jboss.domain.config.dir/domain.xml A relative path which is interpreted to be relative to jboss.domain.config.dir.
--host-config jboss.domain.config.dir/host.xml A relative path which is interpreted to be relative to jboss.domain.config.dir.

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 maintain 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 at 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 apply in both standalone or managed domain mode:

Name Function
-b=<value> Sets system property jboss.bind.address to <value>. See Controlling the Bind Address with -b for further details.
-b<name>=<value> Sets system property jboss.bind.address.<name> to <value> where name can vary. See Controlling the Bind Address with -b for further details.
-u=<value> Sets system property jboss.default.multicast.address to <value>. See Controlling the Default Multicast Address with -u for further details.
--version
-v
-V
Prints the version of JBoss AS to standard output and exits the JVM.
--help
-h
Prints a help message explaining the options and exits the JVM.

Controlling the Bind Address with -b

JBoss AS binds sockets to the IP addresses and interfaces contained in the <interfaces> elements in standalone.xml, domain.xml and host.xml. (See Interfaces and Socket Bindings for further information on these elements.) The standard configurations that ship with JBoss AS includes two interface configurations:

Those configurations use the values of system properties jboss.bind.address.management and jboss.bind.address if they are set. If they are not set, 127.0.0.1 is used for each value.

As noted in Common Parameters, the AS supports the -b and -b<name> command line switches. The only function of these switches is to set system properties jboss.bind.address and jboss.bind.address.<name> respectively. However, because of the way the standard AS configuration files are set up, using the -b switches can indirectly control how the AS binds sockets.

If your interface configurations match those shown above, using this as your launch command causes all sockets associated with interface named "public"  to be bound to 192.168.100.10.

In the standard config files, public interfaces are those not associated with server management. Public interfaces handle normal end-user requests.

Interface names
The interface named "public" is not inherently special. It is provided as a convenience. You can name your interfaces to suit your environment.

To bind the public interfaces to all IPv4 addresses (the IPv4 wildcard address), use the following syntax:

You can also bind the management interfaces, as follows:

In the standard config files, management interfaces are those sockets associated with server management, such as the socket used by the CLI, the HTTP socket used by the admin console, and the JMX connector socket.

Be Careful
The -b switch only controls the interface bindings because the standard config files that ship with JBoss AS sets things up that way. If you change the <interfaces> section in your configuration to ignore the system properties controlled by -b, then setting -b in your launch command will have no effect.

For example, this perfectly valid setting for the "public" interface causes  -b to have no effect on the "public" interface:

The key point is the contents of the configuration files determine the configuration. Settings like -b are not overrides of the configuration files. They only provide a shorter syntax for setting a system properties that may or may not be referenced in the configuration files. They are provided as a convenience, and you can choose to modify your configuration to ignore them.

Controlling the Default Multicast Address with -u

JBoss AS may use multicast communication for some services, particularly those involving high availability clustering. The multicast addresses and ports used are configured using the socket-binding elements in standalone.xml and domain.xml. (See Socket Bindings for further information on these elements.) The standard HA configurations that ship with JBoss AS include two socket binding configurations that use a default multicast address:

Those configurations use the values of system property jboss.default.multicast.address if it is set. If it is not set, 230.0.0.4 is used for each value. (The configuration may include other socket bindings for multicast-based services that are not meant to use the default multicast address; e.g. a binding the mod-cluster services used to communicate on a separate address/port with Apache httpd servers.)

As noted in Common Parameters, the AS supports the -u command line switch. The only function of this switch is to set system property jboss.default.multicast.address. However, because of the way the standard AS configuration files are set up, using the -u switches can indirectly control how the AS uses multicast.

If your socket binding configurations match those shown above, using this as your launch command causes the service using those sockets configurations to be communicate over multicast address 230.0.1.2.

Be Careful
As with the -b switch, the -u switch only controls the multicast address used because the standard config files that ship with JBoss AS sets things up that way. If you change the <socket-binding> sections in your configuration to ignore the system properties controlled by -u, then setting -u in your launch command will have no effect.

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

In a JDBC core module

For better start up server behavior, install the JDBC driver as a core module

As a regular JAR deployment

A simple way to install a JDBC driver into the application server is to deploy it as a regular JAR deployment, the driver must be JDBC-4 compliant. A reason for this might be if 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:

Using security domains

Information can be found at https://community.jboss.org/wiki/JBossAS7SecurityDomainModel

Deployment of -ds.xml files

Starting with JBoss Application Server 7.1.0.Final you have the ability to deploy a -ds.xml file following the schema:

http://docs.jboss.org/ironjacamar/schema/datasources_1_1.xsd

It is mandatory to use a reference to an already deployed / defined <driver> entry.

This feature is primarily intended for development, and thus has a few limitations to be aware of. It can not be altered in any of the management interfaces (consle, CLI, etc). Only limited runtime information is available. Also, password vaults and security domains are not deployable, so these can not be bundled with a datasource deployment.

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

There are two kinds of basic JMS connection-factory:

  • In-VM connection factories can be used by a local client (i.e. one running in the same JVM as the server)
  • Netty connections factories can be used by a remote client. 

There is also a pooled-connection-factory which is special in that it leverages the outbound adapter of the HornetQ JCA Resource Adapter.  It is also special because:

  • It is only available to local clients, although it can be configured to point to a remote server.
  • As the name suggests, it is pooled and therefore provides superior performance to the clients which are able to use it.  The pool size can be configured via the max-pool-size and min-pool-size attributes.
  • It should only be used to send (i.e. produce) messages.
  • It can be configured to use specific security credentials via the user and password attributes.  This is useful if the remote server to which it is pointing is secured.

To be clear, the inbound adapter of the HornetQ JCA RA (which is for consuming messages) is only used by MDBs and is not available to other kinds of clients.

Both a connection-factory a pooled-connection-factory reference a connector declaration.  

A netty-connector is associated with a socket-binding which tells the client using the connection-factory where to connect.

  • A connection-factory referencing a netty-connector is suitable to be used by a remote client to send messages to or receive messages from the server (assuming the connection-factory has an appropriately exported entry).  
  • A pooled-connection-factory referencing a netty-connector is suitable to be used by a local client to send messages to a remote server granted the socket-binding references an outbound-socket-binding pointing to the remote server in question.

An in-vm-connector is associated with a server-id which tells the client using the connection-factory where to connect (since multiple HornetQ servers can run in a single JVM).

  • connection-factory referencing an in-vm-connector is suitable to be used by a local client to either send messages to or receive messages from a local server.  
  • pooled-connection-factory referencing an in-vm-connector is suitable to be used by a local client only to send messages to a local server.

The entry declaration of a connection-factory or a pooled-connection-factory specifies the JNDI name under which the factory will be exposed.  Only JNDI names bound in the "java:jboss/exported" namespace are available to remote clients.  If a connection-factory has an entry bound in the "java:jboss/exported" namespace a remote client would look-up the connection-factory using the text after "java:jboss/exported".  For example, the "RemoteConnectionFactory" is bound by default to "java:jboss/exported/jms/RemoteConnectionFactory" which means a remote client would look-up this connection-factory using "jms/RemoteConnectionFactory".  A pooled-connection-factory should not have any entry bound in the "java:jboss/exported" namespace because a pooled-connection-factory is not suitable for remote clients.

(See standalone/configuration/standalone-full.xml)

JMS Queues and Topics

JMS queues and topics are sub resources of the messaging subsystem.  They are defined in the jms-destinations section.  One can define either a jms-queue or jms-topic.  Each destination must be given a name and contain at least one entry element.

Each entry refers to a JNDI name of the queue or topic.  Keep in mind that any jms-queue or jms-topic which needs to be accessed by a remote client needs to have an entry in the "java:jboss/exported" namespace.  As with connection factories, if a jms-queue or jms-topic has an entry bound in the "java:jboss/exported" namespace a remote client would look it up using the text after "java:jboss/exported".  For example, the following jms-queue "testQueue" is bound to "java:jboss/exported/jms/queue/test" which means a remote client would look-up this jms-queue using "jms/queue/test".  A local client could look it up using "java:jboss/exported/jms/queue/test", "java:jms/queue/test", or more simply "jms/queue/test":

(See standalone/configuration/standalone-full.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-full.xml)

Security Settings for HornetQ addresses and JMS destinations

Security constraints are matched against an address wildcard, similar to the DLQ and redelivery settings.  Note: Multiple roles are separated by spaces.

(See standalone/configuration/standalone-full.xml)

Security Domain for Users

By default, HornetQ will use the "other" JAAS security domain.  This domain is used to authenticate users making connections to HornetQ and then they are authorized to perform specific functions based on their role(s) and the security-settings described above.  This domain can be changed by using security-domain, e.g.:

Deployment of -jms.xml files

Starting with JBoss Application Server 7.1.0.Final you have the ability to deploy a -jms.xml file defining JMS destinations, e.g.:

This feature is primarily intended for development as destinations deployed this way can not be managed with any of the provided management tools (e.g. console, CLI, etc).

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

Domain management

The webservices subsystem is the subsystem that brings the services provided through JBossWS components and which deal with deployment of WS endpoints on the application server.

Structure of the webservices subsystem

Published endpoint address

JBossWS supports rewriting the of the <soap:address> element in endpoint published WSDL contracts. That's useful for controlling the server address that is advertised to clients for each endpoint.

The following elements are available and can be modified (all are optional and require server restart upon modification):

Name Type Description
modify-wsdl-address
boolean If the content of <soap:address> is a valid URL, JBossWS will not rewrite it unless modify-soap-address is true.
If the content of <soap:address> is not a valid URL, JBossWS will rewrite it using the following elements' values.
wsdl-host
string The hostname / IP address to be used for rewriting <soap:address>.
If wsdl-host is set to jbossws.undefined.host, JBossWS uses requesters host when rewriting the <soap:address>
wsdl-port
int Set this property to explicitly define the HTTP port that will be used for rewriting the SOAP address.
Otherwise the HTTP port will be identified by querying the list of installed HTTP connectors.
wsdl-secure-port
int Set this property to explicitly define the HTTPS port that will be used for rewriting the SOAP address.
Otherwise the HTTPS port will be identified by querying the list of installed HTTPS connectors.

Predefined endpoint configurations

JBossWS allows for defining endpoint configurations to be referenced by endpoint implementations. This allows for instance for adding a given handler to any WS endpoint that is marked with a given endpoint configuration (through @org.jboss.ws.api.annotation.EndpointConfig).

JBoss Application Server comes with a default Standard-Endpoint-Config as well as with an example of custom endpoint configuration (Recording-Endpoint-Config) including a recording handler (please reference the JBossWS documentation for details on that).

The Standard-Endpoint-Config is a special endpoint configuration that is automatically used for any endpoint which no other configuration is associated to.
Endpoint configs

Endpoint configs are defined using endpoint-config element; each endpoint config may include properties and handlers set to the endpoints associated to the config.

A new endpoint config can be added as follows:

Handler chains

Each endpoint config may be associated both to PRE and POST handler chains. Each handler chain may include JAXWS handlers. For outbound messages, PRE handler chain handlers are meant to be executed before any handler attached to the endpoints using standard JAXWS means (e.g. using @HandlerChain), while POST handler chain handlers are executed after usual endpoint handlers. For inbound messages, the opposite applies.

* Server inbound messages
Client --> ... --> POST HANDLER --> ENDPOINT HANDLERS --> PRE HANDLERS --> Endpoint

* Server outbound messages
Endpoint --> PRE HANDLER --> ENDPOINT HANDLERS --> POST HANDLERS --> ... --> Client

protocol-binding attribute can be used to set the protocols which the chain needs to be triggered for.

A new handler chain can be added as follows:

Handlers

JAXWS handler can be added in handler chains:

Endpoint-config handler classloading
The class attribute is to be used for providing the full class name of the handler. At deploy time, an instance of that class is created for each referencing deployment; for that to succeed, either the deployment classloader or the classloader for module org.jboss.as.webservices.server.integration need to be able to load the handler class.

Runtime information

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. For a detailed description of the available configuration properties, please consult the project documentation.

Logging


Overview

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:


Why is there a logging.properties file?

You may have noticed that there is a logging.properties file in the configuration directory. This logging configuration is used when the server boots up until the logging subsystem kicks in. If the logging subsystem is not included in your configuration, then this would act as the logging configuration for the entire server.

In the future this file may go away or be automatically generated from the logging subsystem. For most users this file should not be modified.

Note: If the logging.properties is not available during start there will be no logging until the logging subsystems kicks in, this is also the case if the configuration is damaged, the server might exit without any further message.


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


Logging Subsystem Descriptions

root-logger

Defines the root logger for this log context.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
handlers The Handlers associated with this Logger. LIST true false read-write no-services Any

logger

Defines a logger category.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
handlers The Handlers associated with this Logger. LIST true false read-write no-services Any
use-parent-handlers Specifies whether or not this logger should send its output to it's parent Logger. BOOLEAN true false read-write no-services Any
category Specifies the category for the logger. STRING false false read-only   Any

async-handler

Defines a handler which writes to the sub-handlers in an asynchronous thread. Used for handlers which introduce a substantial amount of lag.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
name The handler's name. STRING false false read-only   Any
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
formatter Defines a formatter. STRING true false read-write no-services Any
queue-length The queue length to use before flushing writing INT false false read-write resource-services Any
overflow-action Specify what action to take when the overflowing. The valid options are 'block' and 'discard' STRING false false read-write no-services "BLOCK","DISCARD"
subhandlers The Handlers associated with this asycn handler. LIST true false read-write no-services Any

console-handler

Defines a handler which writes to the console.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
name The handler's name. STRING false false read-only   Any
encoding The character encoding used by this Handler. STRING true false read-write no-services Any
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
formatter Defines a formatter. STRING true false read-write no-services Any
autoflush Automatically flush after each write. BOOLEAN true false read-write no-services Any
target Defines the target of the console handler. The value can either be SYSTEM_OUT or SYSTEM_ERR. STRING true false read-write no-services "System.out","System.err"

file-handler

Defines a handler which writes to a file.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
name The handler's name. STRING false false read-only   Any
encoding The character encoding used by this Handler. STRING true false read-write no-services Any
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
formatter Defines a formatter. STRING true false read-write no-services Any
autoflush Automatically flush after each write. BOOLEAN true false read-write no-services Any
append Specify whether to append to the target file. BOOLEAN true false read-write resource-services Any
file The file description consisting of the path and optional relative to path. OBJECT true false read-write no-services Any

periodic-rotating-file-handler

Defines a handler which writes to a file, rotating the log after a time period derived from the given suffix string, which should be in a format understood by java.text.SimpleDateFormat.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
name The handler's name. STRING false false read-only   Any
encoding The character encoding used by this Handler. STRING true false read-write no-services Any
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
formatter Defines a formatter. STRING true false read-write no-services Any
autoflush Automatically flush after each write. BOOLEAN true false read-write no-services Any
append Specify whether to append to the target file. BOOLEAN true false read-write resource-services Any
file The file description consisting of the path and optional relative to path. OBJECT true false read-write no-services Any
suffix Set the suffix string. The string is in a format which can be understood by java.text.SimpleDateFormat. The period of the rotation is automatically calculated based on the suffix. STRING false false read-write no-services Any

size-rotating-file-handler

Defines a handler which writes to a file, rotating the log after a the size of the file grows beyond a certain point and keeping a fixed number of backups.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
name The handler's name. STRING false false read-only   Any
encoding The character encoding used by this Handler. STRING true false read-write no-services Any
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
formatter Defines a formatter. STRING true false read-write no-services Any
autoflush Automatically flush after each write. BOOLEAN true false read-write no-services Any
append Specify whether to append to the target file. BOOLEAN true false read-write resource-services Any
file The file description consisting of the path and optional relative to path. OBJECT true false read-write no-services Any
rotate-size The size at which to rotate the log file. STRING false false read-write no-services Any
max-backup-index The maximum number of backups to keep. INT false false read-write no-services Any

custom-handler

Defines a custom logging handler. The custom handler must extend java.util.logging.Handler.

Attribute Description Type Allow Null Expression Allowed Access Type Restart Required Allowed Values
name The handler's name. STRING false false read-only   Any
encoding The character encoding used by this Handler. STRING true false read-write no-services Any
level The log level specifying which message levels will be logged by this. Message levels lower than this value will be discarded. STRING true false read-write no-services "ALL","CONFIG","DEBUG","ERROR","FATAL","FINE","FINER","FINEST","INFO","OFF","TRACE","WARN","WARNING"
filter Defines a simple filter type. OBJECT true false read-write no-services "all","any","accept","change-level","deny","level","level-range","match","not","replace"
formatter Defines a formatter. STRING true false read-write no-services Any
class The logging handler class to be used. STRING false false read-only   Any
module The module that the logging handler depends on. STRING false false read-only   Any
properties Defines the properties used for the logging handler. All properties must be accessible via a setter method. LIST false false read-write no-services Any

What is the %s and %E in the pattern-formatter's pattern?

%s is the message

%E is the exception if one exists

JMX

The JMX subsystem registers a service with the Remoting endpoint so that remote access to JMX can be obtained over the exposed Remoting connector.

This is switched on by default in standalone mode and accessible over port 9999 but in domain mode is switched off so needs to be enabled - in domain mode the port will be the port of the Remoting connector for the AS instance to be monitored.

To use the connector you can access it in the standard way using a service:jmx URL:

You also need to set your classpath when running the above example.  The following script covers Linux.  If your environment is much different, paste your script when you have it working.

!/bin/bash

# specify your AS7 folder
export YOUR_AS7_HOME=~/as7

java -classpath $YOUR_AS7_HOME/bin/client/jboss-client.jar:./ JMXExample

You can also connect using jconsole.

If using jconsole use the jconsole.sh and jconsole.bat scripts included in the bin folder of the AS distribution as these set the classpath as required to connect over Remoting.

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

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

The documentation of this functionality can be found at the JBoss OSGi documentation pages.

Integration with AS 7 and reference the the OSGi subsystem in the AS 7 XML configuration file can be found in the Application Server Integration section.

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

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:

You can define more deployment-scanner entries 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

Threads subsystem

Unable to render {include} Couldn't find a page to include called: Threads Subsystem

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
cmp
Enables the deployment of CMP beans
configadmin Enables the deployment and functionality of OSGI applications.
JAXRS Enables the deployment and functionality of JAX-RS applications. This is implemented by the RestEasy project
jdr Turns on Jboss Diagnostic Reporting subsystem
pojo
Enables deployment and functionality of MC beans
sar Enables the deployment of .SAR archives containing MBean services, as supported by previous versions of JBoss Application Server
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.  This file gets overwritten each time the server successfully writes the configuration, if there was an unexpected failure writing the configuration this file is the last known successful write.

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.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.

Snapshots

In addition to the backups taken by the server as described above you can manually take take snapshots which will be stored in the snapshot folder under the _xml_history folder, the automatic backups described above are subject to automatic house keeping so will eventually be automatically removed, the snapshots on the other hand can be entirely managed by the administrator.

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:

Subsequent Starts

For subsequent server starts it may be desirable to take the state of the server back to one of the previously known states, for a number of items an abbreviated reverence to the file can be used: -

Abreviation
Parameter
Description
initial
--server-config=initial
This will start the server using the initial configuration first used to start the server.
boot
--server-config=boot
This will use the configuration from the last successful boot of the server.
last
--server-config=last
This will start the server using the configuration backed up from the last successful save.
v?
--server-config=v?
This will server the _xml_history/current folder for the configuration where ? is the number of the backup to use.
????-?????
--server-config=????-????? The server will be started after searching the snapshot folder for the configuration which matches this prefix.

In addition to this the --server-config parameter can always be used to specify a configuration relative to the jboss.server.config.dir and finally if no matching configuration is found an attempt to locate the configuration as an absolute path will be made.

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 it's 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.