Configuring the Web Server

Most common technologies for creating web applications are JSPs and servlets, these are most commonly deployed in a Apache/Tomcat solution. Tomcat can double up and also be used as a web server serving static content, it can use use virtual hosts and CGI. One problem with Tomcat is that it is a lot slower that an dedicated web server such as Apache (which is the leader in web servers).

JBoss serves web applications using a new Red Hat product called JBoss Web Server, which combines the speed of Apache with the versatility of Apache/Tomcat. JBoss Web Server is built on top of Apache Tomcat 6.0 but is capable of using a native Apache library called Apache Portable Runtime (APR) to attain the speed of the Apache web server.

Some of what I am going to talk about has already been mentioned in my Tomcat section, I will point you in that direction on topics that I have already covered.

Java EE applications are packaged into a WAR (Web Archive) structure defined in the servlet specification. I will be using the below diagram to discuss what a web application structure looks like, this is a simple example but is common, the top-level folder defines the name of the package, this package is a Web Archive package which uses the .war extension, the package could be a single file or an exploded directory, you can place any static content in the top-level directory that your application requires, which may include HTML files, XML files, images, JSPs, etc. There are two important directories in this example WEB-INF and META-INF, both of the directories cannot be access via a URL and are private to the web application.

I have already discuss in detail the above directories in my Tomcat section.

All web applications must have at least the WEB-INF/web.xml deployment descriptor (also known as standard deployment descriptor), the configuration files that provides the server with the necessary information required when deploying an application. A web application can have a proprietary deployment descriptor which can be used to enforce security rules by defining the source of the security data and how that data should be compared to the restricted security role. JBoss has two proprietary deployment descriptors called jboss-web.xml and context.xml.

Deployment Descriptor Files

Each web application must have a web deployment descriptor file called web.xml located in the WEB-INF directory, this file holds standard configuration information for servlets and JSPs

example web.xml <web-app>

    <servlet-name>Oracle Test</servlet-name>

    <servlet-name>Oracle Test</servlet-name>


The next file is the jboss-web.xml also in the WEB-INF directory, this is the main proprietary deployment descriptor file, this file is optional and is normally scant, there are a number of elements that can be used in this file

jboss-web.xml elements
class-loading Used to enable isolated class loading, use this if you want to change the class loading behavior for an application but not necessary the entire server
security-domain Specifies which security domain the application uses for authentication and authorization
context-root Defines the root URL mapped to this application when HTTP requests come in, use this if you want to change the URL context
virtual-host Specifies which virtual host the application belongs to, this must match a virtual host that was defined in the Tomcat server.xml file.
use-session-cookies A boolean flag that indicates whether or not the session should be kept in client cookies
replication-config Specifies when to replicate the HTTP session state throughout a cluster
resource-env-ref Maps the Enterprise Naming Context (ENC) name for a resource-env-ref defined in the web.xml file to the location in the global JNDI namespace, use this if you have defined a resource-env-ref in the web.xml file for an application
resource-ref Maps the Enterprise Naming Context (ENC) name for a resource-ref defined in the web.xml file to the location in the global JNDI namespace, use this if you have defined a resource-ref in the web.xml file for an application
ejb-ref Maps the Enterprise Naming Context (ENC) name for an ejb-ref defined in the web.xml file to the location in the global JNDI namespace.
ejb-local-ref Maps the Enterprise Naming Context (ENC) name for an ejb-local-ref defined in the web.xml file to the location in the global JNDI namespace.
servlet Used to specify servlet-=specific customizations in JBoss Web Server.
Simple example (jboss-web.xml)

JBoss Web Server is built on top of Tomcat and its proprietary deployment descriptor called context.xml, the jboss-web.xml has overridden most of the configuration features making it unnecessary in most cases. The only time this is used is if you are going to be using application-level Tomcat Valves.

There are times when you want a configuration to apply to all web applications, JBoss has global versions of these files which are located in the deployers directory, below is a table detailing application-level and global-level configuration files

Filename Application-level configuration Global-level configuration
web.xml WEB-INF/web.xml deployers/jbossweb.deployer/web.xml
context.xml WEB-INF/context.xml deploy/jbossweb.sar/context.xml
jboss-web.xml WEB-INF/jboss-web.xml None available

Key Files and Directories

JBoss has a number of key files and directories, that live under either deploy and deployers directories

deploy/jbossweb.sar/server.xml Primary server configuration files, used to configure virtual hosts, protocols, ports and request filters
deploy/jbossweb.sar/context.xml Global version of the application-level file by the same name
deploy/jbossweb.sar/jsf-libs Contains libraries necessary for JSF development
conf/web.xml Global version of the application-level file that we discussed above
deployers/jbossweb.deployer/META-INF/war-deployers-jboss-beans.xml Microcontainer configuration file, used to initialize the WAR deployer, it also configures security, class loading and clustering

The server.xml is very much like Tomcats server.xml file (I suggest you have a quick look at my Tomcat section to get up to speed) it comprises of the following elements

Element Description When would you configure it?
Server Represents the entire servlet container likely never
Service Container for multiple connectors that share a single engine likely never
Connector Binds to a particular port and listens for requests using a particular protocol For any changes to the protocol or port that clients use to communicate with the web container
Engine Receives and processes all requests from all connectors in the same service. When you're setting up load-balanced JBoss Web Servers nodes
Realm Defines how security information is handled If you need to change the strategy for mapping X509 certificate chains to a user for authentication purposes
Host Defines virtual hosts You need to add or change the configuration for a domain or hostname mapped to your server
Alias Specifies an alias for Host element that surrounds it If you have multiple names for the same virtual host
Valve Intercepts requests that come into the system and executes code before the request reaches the targeted web component In order to add some sort of monitoring or logging capability to the web container or a particular web application

Like Tomcat two connectors are configured by default a HTTP connector (port 8080) and a AJP connector (port 8009).

The WAR deployer configuration file war-deployers-jboss-beans.xml defines a bean called WarDeployer, the main deployer used for web applications. There are a number of properties at the end of the file that you may wish to change

defaultSecurityDomain The security domain used if you don't explicitly define one in your applications WEB-INF/jboss-web.xml, default is java:/jaas/jboss-web-policy
deleteWorkDirOnContextDestroy Delete the server/xxx/work directory after the application context ends, default is false
These properties are used to configure class loading for web applications.

Virtual Hosts

I have already discussed virtual hosts in my Tomcat section, so pop over to get an ideal what it means, I am only going to show you a quick and dirty on what needs to be configured in JBoss to setup virtual hosting, you need to do the following

Enable the connector to use virtual hosts

<Connector protocol="HTTP/1.1" port="8080"

Note: this would be configured in the server.xml (this is identical to Tomcat)

Define the virtual host

<Engine name="jboss.web" defaultHost="localhost">
  <Host name="localhost" autoDeploy="false" deployOnStartup="false" deployXML="false">

  <Host name="" autoDeploy="false" deployOnStartup="false" deployXML="false">


Note: you can add an alias to map multiple domain names to the same virtual host configuration

Bind an application to a virtual host <jboss-web>

Note: this would be placed in the application WEB-INF/jboss-web.xml file

The last web application aspect you might want to change is the context paths, here are some tips

context-root path <jboss-web>

Note: change this in the jboss-web.xml file
context path of an Enterprise app <application>


Configuring Connectors

There are two ways to configure JBoss

If you have decided to setup the JBoss web server most clients will connect via HTTP or HTTPS, if have are using JBoss as a servlet, JSP and EJB server only then you are probably going to use AJP. I have already discussed the three types of connectors in my Tomcat section section so pop over and take a look at HTTP/HTTPS and AJP to get up to speed.

I am only going to display the already configured setup in the server/xxx/deploy/jbossweb.sar/server.xml file and explain some of the attributes that you could change

Connector Attributes
maxThreads This is used with the HTTP connector which is the maximum number of processing threads that can run concurrently, the default is 200. If the limit is reached the requests will be queued there a number of queuing attributes (see below), but the defaults are more than enough for most installations
minSpareThreads The number of threads the web server tries to keep available above and beyond the number of currently in use, default is 4
maxSpareThreads if more threads than this are idle, then those threads are stopped and deallocated, default is 50
acceptCount or backlog Defines the length of the queue, once the queue is full all request are then refused, default is 10

acceptCount (HTTP)
connectionTimeouts Use this if clients are responding slowly, HTTP connectors have a default of 60 seconds then AJP connector is 0 which means infinite
proxyName and proxyPort Use these if you are going to be behind a proxy, they override values that are provided to your application when your code calls the request.getServerName() and request.getServerPort() servlet methods.
Already configured Connectors
<Connector protocol="HTTP/1.1" port="8080" address="${jboss.bind.address}" connectionTimeout="20000"            redirectPort="8443" />

<Connector protocol="AJP/1.3" port="8009" address="${jboss.bind.address}" redirectPort="8443" />

Using Valves

Again I have already discussed valves in my Tomcat section, valves in JBoss are the same as the Tomcat ones, you can perform certain actions every time a request comes in to the server, you may want to log information, check an IP address, block IP addresses.

You can configure valves at the application-level using the WEB-INF/context.xml file or at the server-level as a sub-element of an engine or a host in the JBoss Web Servers server.xml file.

A valve element must have an attribute called className that points to a Java class, there are a number of Java classes you can use

org.apache.catalina.valves.RequestDumperValve Logs information about a request before and after its processed
org.apache.catalina.valves.AccessLogValve Writes to a logfile that resembles a web server access log, you can customize the log information
org.apache.catalina.valves.FastCommonAccessLogValve Same as above but faster with limited configuration
org.apache.catalina.valves.RemoteAddrValve Allows filtering of requests based on the clients IP address
org.apache.catalina.valves.RemoteHostValve Allows filtering of requests based on the clients hostname
org.apache.catalina.authenicator.SingleSignOn When a user signs into a single application, this valve automatically signs them into all other applications associated with the virtual host for which the valve is defined
org.jboss.web.tomcat.service.sso.ClusteredSingleSignOn This is the same as the SingleSignOn valve but enables the single-sign-on feature to work across a cluster of JBoss servers
org.jboss.web.tomcat.service.jca.CachedConnectionValve Automatically closes all JCA connections when the web request ends, in production you probably want to disable this.