How to configure the Port offset on JBoss AS / WildFly

Do you want to learn how to change the default ports in WildFly application server? Then keep reading this tutorial.

Port offset is an useful tweak which you can configure 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, you can find the port offset definition within the standard-sockets element:

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

13:36:47,186 INFO  [] (Controller Boot Thread) WFLYSRV0060: Http management interface listening on
13:36:47,187 INFO  [] (Controller Boot Thread) WFLYSRV0051: Admin console listening on
13:36:47,187 INFO  [] (Controller Boot Thread) WFLYSRV0025: WildFly Full 14.0.0.Final (WildFly Core 6.0.1.Final) started in 20057ms - Started 1057 of 1226 services (359 services are lazy, passive or on-demand)

If you want to apply the change permanently in your configuration, then you can achieve the same result with:


You can also use Environment Variables (instead of System Properties) to define your port settings. Check this article: How to use environment variables in WildFly configuration (standalone.xml or host.xml)

Assigning a Fixed port to WildFly

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"/>

Binding a single interface to an IP Address

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 that you are using in the single channels.

Configuring Client Mappings

By using a client-mapping definition in your socket-binding element you can specify that clients connecting to an inbound socket must use the destination address specified in the mapping. See this example:

<socket-binding name="remoting" port="4447">
    <client-mapping destination-address="" destination-port="9988"/>

By using the client-mapping attribute you can leverage advanced network topologies that use either network address translation or include bindings on multiple network interfaces. If you are using multiple mappings, each mapping is evaluated in declared order. The first successful match determines the destination for the mapping.

Configuring Port Offset using the Web Console

If you prefer, you can also use the Web Console to edit your Port Offset settings. Log into the Console then select the Configuration Tab | Socket Binding:

jboss port offset

Click on the above link to edit the value for jboss.socket.binding.port-offset.

Domain mode

When running in Domain mode, you cannot use the property -Djboss.socket.binding.port-offset at start up to shift the port of your Domain Servers.

You must apply the port offset change through the Host Controller that govern the server:


This results in the following change in the host.xml configuration file:

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