HOWTO: Change Default Port Numbers in JBoss

Introduction

One of the more unintuitive parts of JBoss involves changing default port numbers that services listen on.  If you are relatively new to JBoss and are setting up a server virtually hosting multiple instances of jboss, you can spend a fair amount of time figuring out how to do this.  In apache, changing ports is simply a matter of modifying a Listen statement and possibly modifying a virtual server entry.  In tomcat, it is pretty much just as easy.  With JBoss, it is a bit more complicated because there are many different ports tied to an application server instance and you really do not want to set something up that only you will understand because we all want to get promoted, right?  Although you can grep through the configuration files, it is an error-prone process because, depending upon the port you are looking to change, it can be defined in multiple places.

JBoss does have a built-in facility for managing listening ports.  Port number assignments in the JBoss Application Server are configured and managed through the use of the Bindings Manager.  The JBoss Bindings Manager can be loaded as part of jboss-service.xml for your server instance. For the examples in this article, I will use the jboss-service.xml from the "default" server instance.

Using the Bindings Manager with JBoss 4

Remove the comments surrounding the Binding Manager configuration from your server's jboss-service.xml so that the following is displayed:

 <mbean code="org.jboss.services.binding.ServiceBindingManager"
  name="jboss.system:service=ServiceBindingManager">
  <attribute name="ServerName">ports-01</attribute> 
  <attribute name="StoreURL">${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml</attribute>
  <attribute name="StoreFactoryClassName">org.jboss.services.binding.XMLServicesStoreFactory</attribute>
</mbean>

Note that the ServerName parameter is utilizing ports-01.

In addition, the StoreURL parameter is presently pointing to a sample configuration file.  Open that file up in your editor now. This file contains four port configuration sections.  Each port is incremented by 100 from the previous set of ports.  For example, the default ajp port is 8009.  The port number assigned to this set in the ports-01 configuration is 8109, the number assigned in the ports-02 configuration is 8209, etc.  The default http port is 8080.  This is set to 8180 in the ports-01 configuration, 8280 in the ports-02 configuration—you get the idea.

Save this file to your server's conf directory as binding-manager.xml(same location as jboss-service.xml).  You do not need to make any changes to this file for this example.

Modify your server instance's jboss-service.xml file and change the StoreURL configuration in the binding manager section from:

${jboss.home.url}/docs/examples/binding-manager/sample-bindings.xml

to:

${jboss.server.base.dir}/${jboss.server.name}/conf/binding-manager.xml

Start up your server and it is now listening on the set of ports from the ports-01 section of the binding-manager.xml file.  If you are running JBoss on Windows, depending upon the service wrapper you are using, you might have to delete the service and re-create it.  I've seen some service wrappers (like the one that ships with some versions of SpringSource Enterprise Ready Server for tomcat) that does not re-read configuration updates unless the service is removed and re-installed.

Using the Bindings Manager with JBoss 5

With the 5.0 release of the JBoss Application Server, the Bindings Manager is no longer an optional component.  Located the bootstrap directory, which is a sub-directory of your server instance's conf directory is a file named bindings.xml.

This file, although laid out in a different format, duplicates the port assignments from the JBoss Application Server 4.0 Binding Manager.   Interestingly, instead of specifying actual ports, there is a function in the file that increments the default port assignments by 100 if using the ports-01 setting, by 200 if using the ports-02 setting, and by 300 if using the ports-03 setting.

If you want to change your server's port assignments so that it uses ports from the ports-01 setting, all you need to do is append a switch to your run.sh|bat file.  If we want to run an instance that listens on the ports-01 assigned ports, for example, add:

-Djboss.service.binding.set="ports-01"
to your run.sh|bat. Restart JBoss to reflect your changes.


Creative Commons Attribution-ShareAlike 3.0 Unported