High Level Overview

Ant scripts drive the generation of JBoss servers, which are configured based on specifications in properties files. Much of this document describes how these properties are to be set. A detailed overview of the properties themselves is here.

The process for generating servers, in high-level overview, is as follows:

• For the servers to be generated, specify the names, base port-assignments, and port-assignment-method in one of the following two ways:
  • If the generated servers are to use ports incremented from a base set of ports:
    • Specify the names of the servers to be created (in JBOSS_HOME/server) in a file whose name is passed to Ant as server.names.properties as described here
    • Specify the base set of ports (multiple servers will be incremented from these levels) in a file whose name is passed to Ant as initial.bindings.properties, as described here (note the defaults may well work for you, depending on what ports are available on your target server host!).
  • If each generated server is to use a port incremented from a base value (e.g., ports to be used are in a range such as 10000-10019):
    • Specify the names and base port value of the servers to be created (in JBOSS_HOME/server) in a file whose name is passed to Ant as server.names.properties as described here
• Assure that an XML properties file exists for each of the servers you wish to generate, as described in the Overview. The name of each such property is: ${your-server-name}-properties.xml.
• Be certain prerequisites are met (cf. Prerequisites), above, particularly that you have the jca-access project checked out in your workspace (CVSHOME).
• Run the default target (build-servers) in servant/jboss4/build.xml, passing in appropriate parameters (-Dparameter.name=parameter.value). Appropriate parameters include:

  deploy.mode

  Always specify (as test, qa, or prod).

  server.names.properties

  Specify unless the contents of servant/jboss4/conf/default-server-set.properties will suffice.

  initial.bindings.properties

  Only necessary if incrementing from a set of port values (as opposed to a base value). No need to specify for ports incremented from a set unless the ports generated with servant/jboss4/binding-manager/default-bindings.properties conflict with those already in use on the machine where the JBoss servers will be run. Developers building servers to match those that will be deployed to integration-test, qa, or production machines will probably want to use the integration-test server's bindings properties.

  clean.generated.servers

  delete servers listed in server.names.properties and service-bindings.xml prior to generating new servers

  localhost.access.only

  generate servers that can be accessed from the host machine only - i.e., servers only listen for requests from localhost (127.0.0.1)

Overview

The procedure described in this document involves setting properties in an Ant XML Property file, and running an Ant target. The properties files and build.xml file can be found in the jboss directory of the servant project (cf. Prerequisites, above)

The properties to be set and the target to be run are described in this HowTo document.

In overview, for each generated-server specified in the configuration file described (cf. here), the server generation script:

• configures a server's port-settings based either on:
  • a standard set of base values (auto-incremented if multiple servers are generated), or on an non-standard set of base values if so-specified (cf. here)
  • a base value specified alongside the generated server's name in the configuration file described here
• copies server components from the server/default directory under JBOSS_HOME
• copies third-party library files into embedded Tomcat server's common/lib directory (cf. here)
• copies third-party library files into server's /lib directory (cf. here)
• copies third-party client files into the JBoss /client directory (cf. here)
• enables HTTP and HTTPS connectors in the JBoss server if a web server is not to be deployed to handle http and https requests (cf. here)
• configures server's basic services, based on server-props.services.files property (cf. here)
• configures server's datasources, based on server-props.datasource.files property (cf. here)
• configures server's application policies (security), based on server-props.policy.files property (cf. here)
• configures keytab file references for Kerberos authentication of the server via JGSS (cf. here)
• renames and secures jmx-console application (cf. here)
• generates and configures references to a self-signed X.509 certificate used for the JBoss-Tomcat SSL/TLS connector (cf. here)
• configures server's optional services (jms, axis, etc.), based on appropriate property settings (cf. here)

Not every configurable property is listed in the overview above; but all configurable properties are described in this document. Also, additional (non-configurable) tasks are performed by the Ant script that generates servers, such as setting appropriate UNIX permissions on shell scripts; non-configurable tasks are not described in this document.

Specifying generated server(s) name(s)

Any number of servers may be generated. The names of servers to be generated are specified in a property named server-names-list, located in the file conf/default-server-set.properties. An alternate file in which the server-names-list is specified may be passed as a parameter to the top-level servant/jboss build script (build.xml), as follows:

-Dserver.names.properties=conf/your-server-set-file-name.properties

The value of server-names-list is dependent on whether or not use-base-value-port-incrementing is set (to any value) or not-set. This is described in detail in comments to conf/default-server-set.properties, and is summarized below. [The very short summary: if use-base-value-port-incrementing is set, port-specification occurs via the token(s) in server-names-list as described in the bulleted list below; otherwise, cf. here.]

• if use-base-value-port-incrementing is NOT set
  • the value of server-names-list is a comma delimited list of server names
  • each server name is one token
  • there should be no spaces in the value of this property
  • example: server1,server2,server3,server4
• if use-base-value-port-incrementing is set (to any value)
  • the value of server-names-list is a comma delimited list of server names and base port values
  • each server name is delimited from its base port value by a colon (:)
  • the ports for a server will be incremented from the base-port value; e.g., if the generated server uses 12 ports, and the server name:port token is my-server:10000, the generated server will use ports 10000-10011
  • there should be no spaces in the value of this property
  • example: server1:10000,server2:10020,server3:10040,server4:10060

For each named server in server-names-list, an XML properties file must exist in the /conf directory, and must be named {server-name}-properties.xml (e.g., streek-reference-properties.xml). The XML properties files must conform to the DTD conf/dtd/servant-properties.dtd.

When choosing names for servers, be sure that they contain no spaces (e.g., no spaces whatsoever should occur in the comma-delimited list servers-names-list), nor may they contain characters that are disallowed in filenames on the filesystem where servers will be deployed.

Note that each generated server's port bindings will be specified in JBOSS_HOME/server/service-bindings.xml .

Specifying non-standard port values

A standard set of port bindings are specified in servant/jboss4/binding-manager/default-bindings.properties.

This set of bindings is used for the first named server in the list contained in the property named server-names-list (cf. here for more info); the values of bound ports are incremented for any additional servers generated. The increment values are set in the configure-bindings target of servant/jboss4/build-servers.xml.

Should need arise, an alternate set of port values may be specified. The non-standard values should be written to a file in the same directory as default-bindings.properties (e.g., servant/jboss4/binding-manager/my-bindings.properties). To enable use of this alternate set of values, pass the property initial.bindings.properties as a parameter to the top-level servant/jboss build script (build.xml), as follows:

-Dinitial.bindings.properties=binding-manager/your-bindings-file-name.properties

Specifying server name in XML Properties file

Specifying application family name in XML Properties file

Specifying server-specific JVM arguments

Enabling HTTP and HTTPS Connectors

This property governs whether HTTP and HTTPS connectors are enabled or not in generated servers.

The HTTP and HTTPS connectors should not be enabled if a web server is to be deployed in front of JBoss to handle HTTP and HTTPS requests.

Optional Services: setting additional properties

Additional services that may be enabled by appropriately setting properties in the conf/streek-reference-properties.xml file include JbossMail, Java Message Service (JMS), and Apache-Axis (web services).

Specify files to exclude from template JBoss server

A typical value for this node is: **/CVS/**, **/data/**, **/log/**, **/tmp/**, **/work/**, **/jms/jbossmq-destinations-service.xml**, **/mail-service.xml

If JMS is not enabled (cf. here), add to the above: deploy/jms/**

Specifying JMS-specific files to copy

Note that mail-queue-service.xml must be in this list if JBossMail is enabled (cf. here).

Specifying third-party files for embedded Tomcat server's common/lib

Third-party software deployed to this directory is utilized by applications deployed to the embedded Tomcat server.

Third-party jar files commonly specified here for use by Streek applications include:

commons-beanutils-*.jar

required when deploying an application that utilizes Struts (e.g., commons-beanutils/jars/commons-beanutils-1.7.0.jar).

commons-digester-*.jar

required when deploying an application that utilizes Struts (e.g., commons-digester/jars/commons-digester-1.7.jar).

Specifying third-party files for server library

Third-party software deployed to this directory is utilized by applications deployed to the generated server.

Third-party jar files commonly specified here for use by Streek applications include:

castor*.jar

Castor is used to bind Java objects to XML documents and relational tables (e.g., castor/jars/castor-0.9.4.3.jar).

ojdbc14.jar

Oracle JDBC drivers for Java version 1.4.x (e.g., ojdbc14/jars/ojdbc14-9.0.2.0.0)

Specifying third-party files for JBoss /client directory

Third-party software deployed to this directory is utilized by clients (such as monitors and application-testing classes) of applications running in a generated JBoss server.

Third-party client code commonly used in Streek applications includes:

junit*.jar

JUnit is unit-testing software (e.g., junit/jars/junit-3.8.1.jar).

Specifying basic JBoss services

Minimal or required filenames in this list are given below in emphasized text (note epilogue.ent, at the end of the list). Omit these elements only if you are certain of what you're doing. The descriptions below may be augmented in the *.ent files themselves.

prologue.ent

jboss-service.xml prolog

jsr77-manager.ent

J2EE management mappings (e.g., SAR, EAR, WAR, EJB Deployers; JNDI; JMS; etc.)

service-binding-manager.ent

Binding service manager for port/host mapping

webservice-classloader.ent

dynamic class loading for RMI access to the server EJBs

log4j.ent

log4j (apache logging) initialization

jndi.ent

JNDI service

security-manager.ent

security configuration, including JAAS security manager

xmbean-persistence.ent

XMBeanAttributePersistenceService

threadpool-service.ent

Basic ThreadPool Service

jdbc-type-mapping-metadata.ent

JDBC Type Mapping Metadata

bean-cache-monitor.ent

JMX monitoring of the bean cache. This file must be edited (per instructions in its comments) to enable monitoring.

entity-lock-monitor.ent

JMX monitoring of entity bean locking. This file must be edited (per instructions in its comments) to enable monitoring.

jmx-invokers.ent

Invokers to the JMX node

rmi-classloader.ent

RMI service

transaction-managers.ent

transaction management

deployment-scanner.ent

hot deployment & undeployment of archives

epilogue.ent

jboss-service.xml epilog

Specifying Application Policies (JBoss server's login-config.xml)

Minimal or required filenames in this list are given below in emphasized text (note epilogue.ent, at the end of the list). Omit these minimal or required elements only if you are certain of what you're doing! Note that application-specific policies need (should) not be included unless the application in-question is to be deployed in the server(s) being generated. The descriptions below may be augmented in the *.ent files themselves

Application-specific database realm entities are generally not included as separate files (as of February 2005); instead, these nodes are incorporated in the application- & deployment-specific entity file. Similarly, application-specific jgss service nodes are incorporated in the application- & deployment-specific entity file.

prologue.ent

login-config.xml prolog

client-login.ent

policy used by clients within the application server VM

default-policy.ent

used by any security domain that does not have an application-policy entry with a matching name

hsql-dbrealm.ent

policy for Hypersonics data source

jmx-console-${deploy.mode}.ent

policy for secured jmx-console application

jggs-service-{deploy-mode}.ent

Depracated Kerberos authentication of the server via jgss, using a server-specific keytab file. Application-specific jgss policies replace this policy; they are normally included in {application-name}-{deploy-mode}.ent

{application-name}-{deploy-mode}.ent

application policy for the application named {application-name} deployed in {deploy-mode}, which may include a login stack, a database realm, and/or a jgss-service node

{application-name}-dbrealm.ent

Depracated application policy for a database realm for the application named {application-name} deployed in {deploy-mode}; as of Feb 2005, practice is to include a database realm application policy node in the {application-name}-{deploy-mode}.ent file

calnet-krb-test.ent

application policy for courseweb, including CalNet authentication and courseweb-specific roles policies

jbossmq.ent

policy for JMS message queues (omit if not used; may require editing if needed)

jxdev-dbrealm.ent

policy for JCA connector

epilogue.ent

login-config.xml epilog

Specifying Data Sources

Generally, the only data sources needed in a JBoss server are those required by applications that will run in that server - see caveat re: Hypersonic database, below.

The local, Hypersonic database (datasource configuration file: hsqldb-ds.xml) is used as a default data source, and must be included in the list of datasources, as the generated server will utilize it for internal processes; omission of hsqldb-ds.xml from this list will cause other services to fail.

JGSS Properties (kerberos keytab file references)

The properties described in this section need only be set if policies that utilize JGSS handshaking are included in the generated server(s) (cf. Application Policies section in this document).

If Kerberos authentication of the server via JGSS is to be implemented, a keytab for the server host must exist on the filesystem. The principal name corresponding to this keytab and its location in a secure directory on the server host's filesystem are specified, for each deployment mode, via properties described above.

Self-generated Certificate Properties

In order to enable SSL-encrypted access to applications, a signed certificate must be available to JBoss-Tomcat. The properties described in this section are employed in creation, deployment, and configuration of a keystore containing a generated, self-signed X.509 certificate.

Note that the build script only uses the indicated four elements of the distinguished name.

Setting JBossMail properties

These properties should be set if server-props/enable.mail is included in the XML Properties file (cf. here).

Setting JMX Console properties

Generating JBoss server instances

After setting environment variables and configuring the conf/streek-reference-properties.xml file appropriately - as described above - run the Ant target build-servers from the build.xml in the jboss directory of the servant project. The target build-servers is the default target in this build script.

After a successful build, run and test the generated server(s).

Running a JBoss server instance

To run a JBoss server, you may either:

• run the appropriate shell script in JBOSS_HOME/bin (e.g., run-myservername.sh) [preferred]
• type your OS's equivalent of the following in a console window (or include in a shell script or .bat file):
  
  JBOSS_HOME/bin/run -c <your-server-name> [-b 127.0.0.1]
  
  
• or, to run the server and send console output to a file, type your OS's equivalent of the following in a console window (or include in a shell script or .bat file):
  
  JBOSS_HOME/bin/run -c <your-server-name> [-b 127.0.0.1] > %JBOSS_HOME%/server/<your-server-name>/log/console.log
  

Note that OS-appropriate reference to the environment variable JBOSS_HOME is necessary if the examples given above are to work properly.

The "[-b 127.0.0.1]" is an [optional] switch that, if included, causes JBoss to listen ONLY for requests coming from localhost. The shell scripts in JBOSS_HOME/bin include this switch if the localhost.access.only property is set when the servers are built (cf. note on Ant runtime parameters, above, for more info).

Determining ports on which JBoss servers are listening

To determine which port(s) the server(s) are listening on, examine the configuration file JBOSS_HOME/server/service-bindings.xml. The port bindings for each generated server are assigned in this file. Ports on which JBoss are listening are also emitted in the console log.

Testing JBoss server instances

For each server you wish to test, start the server and be sure you know which port the server is using to listen for HTTP requests (if Apache is running in front of your JBoss instance, you'll want to make sure that mod_jk2 is properly set up as well!).

To test, point a browser at the server, e.g.: http://localhost:<your-port-number> ... if you see the JBoss application server home page in your browser, your server is running and you are ready to examine whether it is configured as you intended (via the JMX console, etc.).