Chapter 18. Configuring Remoting 18.1. About the remoting subsystem The remoting subsystem allows you to configure inbound and outbound connections for local and remote services as well as the settings for those connections. The JBoss Remoting project includes the following configurable elements: the endpoint, connectors, http-connector, and a series of local and remote connection URIs. For the majority of use cases, you might not need to configure the remoting subsystem. If you use custom connectors for your application, you must configure the remoting subsystem. Applications that act as remoting clients, such as Jakarta Enterprise Beans, need separate configuration to connect to a specific connector. Default Remoting Subsystem Configuration <subsystem xmlns="urn:jboss:domain:remoting:4.0"> <endpoint/> <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm"/> </subsystem> See Remoting Subsystem Attributes for a full list of the attributes available for the remoting subsystem. The remoting endpoint The remoting endpoint uses the XNIO worker declared and configured by the io subsystem. See Configuring the Endpoint for details on how to configure the remoting endpoint. connector The connector is the main remoting configuration element of the JBoss Remoting project, which is used to allow external clients to connect to the server on a given port. Clients that require a connection to the server through a connector must use the Remoting remote protocol in the URL referring to the server, for example, remote://localhost:4447. You can configure multiple connectors. Each connector consists of a <connector> element with several sub-elements and few other attributes, such as socket-binding and ssl-context . Several JBoss EAP subsystems can use the default connector. Specific settings for the elements and attributes of your custom connectors depend on your applications. Contact Red Hat Global Support Services for more information. See Configuring a Connector for details on how to configure connectors. http-connector The http-connector element is a special connector configuration element. An external client can use this element to connect to the server by using the HTTP upgrade feature of undertow . With this configuration, the client first uses the HTTP protocol to establish a connection with a server and then uses the remote protocol over the same connection. This helps clients that use different protocols to connect over the same port, such as the default port 8080 of undertow . Connecting over the same port reduces the number of open ports on the server. Clients that require a connection to the server through HTTP upgrade must use the remoting remote+http protocol for unencrypted connections or the remoting remote+https protocol for encrypted connections. Outbound connections You can specify three different types of outbound connections: An outbound connection , specified by a URI A local outbound connection , which connects to a local resource such as a socket A remote outbound connection , which connects to a remote resource and authenticates using a security realm Additional configuration Remoting depends on several elements that are configured outside of the remoting subsystem, such as the network interface and IO worker. For more information, see Additional Remoting Configuration . 18.2. Configuring the Endpoint Important In JBoss EAP 6, the worker thread pool was configured directly in the remoting subsystem. In JBoss EAP 7, the remoting endpoint configuration references a worker from the io subsystem. JBoss EAP provides the following endpoint configuration by default. <subsystem xmlns="urn:jboss:domain:remoting:4.0"> <endpoint/> ... </subsystem> Updating the Existing Endpoint Configuration Creating a New Endpoint Configuration Deleting an Endpoint Configuration See Endpoint Attributes for a full list of the attributes available for the endpoint configuration. 18.3. Configuring a Connector The connector is the main configuration element relating to remoting and contains several sub-elements for additional configuration. Updating the Existing Connector Configuration Creating a New Connector Deleting a Connector For a full list of the attributes available for configuring a connector, please see the Remoting Subsystem Attributes section. 18.4. Configuring an HTTP Connector The HTTP connector provides the configuration for the HTTP upgrade-based remoting connector. JBoss EAP provides the following http-connector configuration by default. <subsystem xmlns="urn:jboss:domain:remoting:4.0"> ... <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm"/> </subsystem> By default, this HTTP connector connects to an HTTP listener named default that is configured in the undertow subsystem. For more information, see Configuring the Web Server (Undertow) . Updating the Existing HTTP Connector Configuration Creating a New HTTP Connector Deleting an HTTP Connector See Connector Attributes for a full list of the attributes available for configuring an HTTP connector. 18.5. Configuring an Outbound Connection An outbound connection is a generic remoting outbound connection that is fully specified by a URI. Updating an Existing Outbound Connection Creating a New Outbound Connection Deleting an Outbound Connection See Outbound Connection Attributes for a full list of the attributes available for configuring an outbound connection. 18.6. Configuring a Remote Outbound Connection A remote outbound connection is specified by a protocol, an outbound socket binding, a username and a security realm. The protocol can be either remote , http-remoting or https-remoting . Updating an Existing Remote Outbound Connection Creating a New Remote Outbound Connection Deleting a Remote Outbound Connection See Remote Outbound Connection Attributes for a full list of the attributes available for configuring a remote outbound connection. 18.7. Configuring a Local Outbound Connection A local outbound connection is a remoting outbound connection with a protocol of local , specified only by an outbound socket binding. Updating an Existing Local Outbound Connection Creating a New Local Outbound Connection Deleting a Local Outbound Connection See Local Outbound Connection Attributes for a full list of the attributes available for configuring a local outbound connection. 18.8. Additional Remoting Configuration There are several remoting elements that are configured outside of the remoting subsystem. IO worker Use the following command to set the IO worker for remoting: See Configuring a Worker for details on how to configure an IO worker. Network interface The network interface used by the remoting subsystem is the public interface. This interface is also used by several other subsystems, so exercise caution when modifying it. <interfaces> <interface name="management"> <inet-address value="USD{jboss.bind.address.management:127.0.0.1}"/> </interface> <interface name="public"> <inet-address value="USD{jboss.bind.address:127.0.0.1}"/> </interface> <interface name="unsecure"> <inet-address value="USD{jboss.bind.address.unsecure:127.0.0.1}"/> </interface> </interfaces> In a managed domain, the public interface is defined per host in its host.xml file. Socket binding The default socket binding used by the remoting subsystem binds to port 8080 . For more information about socket binding and socket binding groups, see Socket Bindings . Secure transport configuration Remoting transports use STARTTLS to use a secure connection, such as HTTPS, Secure Servlet, if the client requests it. The same socket binding, or network port, is used for secured and unsecured connections, so no additional server-side configuration is necessary. The client requests the secure or unsecured transport, as its needs dictate. JBoss EAP components that use remoting, such as Jakarta Enterprise Beans, ORB, and the Java Messaging Service provider, request secured interfaces by default. Warning STARTTLS works by activating a secure connection if the client requests it, and otherwise defaults to an unsecured connection. It is inherently susceptible to a man-in-the-middle exploit, where an attacker intercepts the request of the client and modifies it to request an unsecured connection. Clients must be written to fail appropriately if they do not receive a secure connection, unless an unsecured connection is an appropriate fall-back.

Commands:
<subsystem xmlns="urn:jboss:domain:remoting:4.0"> <endpoint/> <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm"/> </subsystem>
<subsystem xmlns="urn:jboss:domain:remoting:4.0"> <endpoint/> </subsystem>
/subsystem=remoting/configuration=endpoint:write-attribute(name=authentication-retries,value=2)
reload
/subsystem=remoting/configuration=endpoint:add
/subsystem=remoting/configuration=endpoint:remove
reload
/subsystem=remoting/connector=new-connector:write-attribute(name=socket-binding,value=my-socket-binding)
reload
/subsystem=remoting/connector=new-connector:add(socket-binding=my-socket-binding)
/subsystem=remoting/connector=new-connector:remove
reload
<subsystem xmlns="urn:jboss:domain:remoting:4.0"> <http-connector name="http-remoting-connector" connector-ref="default" security-realm="ApplicationRealm"/> </subsystem>
/subsystem=remoting/http-connector=new-connector:write-attribute(name=connector-ref,value=new-connector-ref)
reload
/subsystem=remoting/http-connector=new-connector:add(connector-ref=default)
/subsystem=remoting/http-connector=new-connector:remove
/subsystem=remoting/outbound-connection=new-outbound-connection:write-attribute(name=uri,value=http://example.com)
/subsystem=remoting/outbound-connection=new-outbound-connection:add(uri=http://example.com)
/subsystem=remoting/outbound-connection=new-outbound-connection:remove
/subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:write-attribute(name=outbound-socket-binding-ref,value=outbound-socket-binding)
/subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:add(outbound-socket-binding-ref=outbound-socket-binding)
/subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:remove
/subsystem=remoting/local-outbound-connection=new-local-outbound-connection:write-attribute(name=outbound-socket-binding-ref,value=outbound-socket-binding)
/subsystem=remoting/local-outbound-connection=new-local-outbound-connection:add(outbound-socket-binding-ref=outbound-socket-binding)
/subsystem=remoting/local-outbound-connection=new-local-outbound-connection:remove
/subsystem=remoting/configuration=endpoint:write-attribute(name=worker, value= WORKER_NAME )
<interfaces> <interface name="management"> <inet-address value="USD{jboss.bind.address.management:127.0.0.1}"/> </interface> <interface name="public"> <inet-address value="USD{jboss.bind.address:127.0.0.1}"/> </interface> <interface name="unsecure"> <inet-address value="USD{jboss.bind.address.unsecure:127.0.0.1}"/> </interface> </interfaces>