Configuring port offset on JBoss AS / WildFly

User Rating: 5 / 5

Star ActiveStar ActiveStar ActiveStar ActiveStar Active

Port offset is an useful tweak which can be applied to execute several application servers on the same machine. A typical usage of the port-offset is for creating a vertical cluster, with multiple nodes on the same machine.

In standalone mode, the port offset is contained in the standard-sockets definition:

<socket-binding-group name="standard-sockets" default-interface="public"  

        <socket-binding name="management-http" interface="management" port="${}"/>
        <socket-binding name="management-https" interface="management" port="${}"/>
        <socket-binding name="ajp" port="${jboss.ajp.port:8009}"/>
        <socket-binding name="http" port="${jboss.http.port:8080}"/>
        <socket-binding name="https" port="${jboss.https.port:8443}"/>
        <socket-binding name="txn-recovery-environment" port="4712"/>
        <socket-binding name="txn-status-manager" port="4713"/>
        <outbound-socket-binding name="mail-smtp">

            <remote-destination host="localhost" port="25"/>



As you can see it contains a Beanshell expression which means, unless the jboss.socket.binding.port-offset is set, it evaluates to 0 so to standard sockets.

So by starting the standalone server with: -Djboss.socket.binding.port-offset=100

 ...will shift all ports by 100. This means also the management bindings, such as management-http and management-https 

 jboss wildfly port offset

 A common pitfall: if you remove the system property from the configuration as follows:

 <socket-binding-group name="standard-sockets" default-interface="public"  port-offset="100">

 Then passing the system properties will be non-effective at startup: -Djboss.socket.binding.port-offset=250

Another thing that not every administrator knows, is that you can assign a fixed port value to a binding. This is usually the case of the HTTP port which is often decided with different rules other than port offset. You can set a fixed port bindings by CLI as follows:


This results in the following:

<socket-binding name="http" port="${jboss.http.port:8080}" fixed-port="true"/>

Finally, one tricky question could be, how do you bind just one channel (let's say http) to an IP address, while keeping the others on the default interface (loopback) ? That's not too complex to do: you have to define one interface at first with your binding rule: 


  . . . .

	<interface name="allIPs">

            <inet-address value="${jboss.bind.address:}"/>



Now you can use the interface attribute on the single socket binding:


This way, you can mix and match the inet address used by the single channels.

Domain mode

The same considerations are also for the Domain mode. You must however remember that in Domain mode, the port offset is configured on the single servers into the file host.xml:

<server name="server-two" group="main-server-group" auto-start="true">
            <socket-bindings port-offset="150"/>

Related articles available on

JBoss MBeans POJO

JMX MBean services are the core building blocks of the JBoss Appl

How to a dump of JNDI tree with JMX console ?

#2 JBoss Howto. This is the recipe of the day

How to configure JBoss to bind to a different IP ?

  If you want to change the jboss.bind.address property use the 

How to shut down JBoss from remote ?

JBoss recipe of the day

How to create multiple instances of an Mbean?

  Supposing you need two instances of an MBean, let's say one fo

JBoss classloader issues

By default JBoss (prior to version 3.2) uses a flat class loading