Chapter 17. Configuring Remoting
17.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.
JBoss Remoting includes the following configurable elements: the endpoint, connectors, and a series of local and remote connection URIs. Most people will not need to configure the remoting
subsystem at all, unless they use custom connectors for their own applications. Applications that act as remoting clients, such as EJBs, 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. Multiple connectors are allowed. Each connector consists of a <connector>
element with several sub-elements, and few other attributes. The default connector is used by several JBoss EAP subsystems. 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.
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.
17.2. Configuring the Endpoint
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
/subsystem=remoting/configuration=endpoint:write-attribute(name=authentication-retries,value=2)
reload
Creating a New Endpoint Configuration
/subsystem=remoting/configuration=endpoint:add
Deleting an Endpoint Configuration
/subsystem=remoting/configuration=endpoint:remove
reload
See Endpoint Attributes for a full list of the attributes available for the endpoint configuration.
17.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
/subsystem=remoting/connector=new-connector:write-attribute(name=socket-binding,value=my-socket-binding)
reload
Creating a New Connector
/subsystem=remoting/connector=new-connector:add(socket-binding=my-socket-binding)
Deleting a Connector
/subsystem=remoting/connector=new-connector:remove
reload
For a full list of the attributes available for configuring a connector, please see the Remoting Subsystem Attributes section.
17.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
/subsystem=remoting/http-connector=new-connector:write-attribute(name=connector-ref,value=new-connector-ref)
reload
Creating a New HTTP Connector
/subsystem=remoting/http-connector=new-connector:add(connector-ref=default)
Deleting an HTTP Connector
/subsystem=remoting/http-connector=new-connector:remove
See Connector Attributes for a full list of the attributes available for configuring an HTTP connector.
17.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
/subsystem=remoting/outbound-connection=new-outbound-connection:write-attribute(name=uri,value=http://example.com)
Creating a New Outbound Connection
/subsystem=remoting/outbound-connection=new-outbound-connection:add(uri=http://example.com)
Deleting an Outbound Connection
/subsystem=remoting/outbound-connection=new-outbound-connection:remove
See Outbound Connection Attributes for a full list of the attributes available for configuring an outbound connection.
17.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
/subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:write-attribute(name=outbound-socket-binding-ref,value=outbound-socket-binding)
Creating a New Remote Outbound Connection
/subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:add(outbound-socket-binding-ref=outbound-socket-binding)
Deleting a Remote Outbound Connection
/subsystem=remoting/remote-outbound-connection=new-remote-outbound-connection:remove
See Remote Outbound Connection Attributes for a full list of the attributes available for configuring a remote outbound connection.
17.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
/subsystem=remoting/local-outbound-connection=new-local-outbound-connection:write-attribute(name=outbound-socket-binding-ref,value=outbound-socket-binding)
Creating a New Local Outbound Connection
/subsystem=remoting/local-outbound-connection=new-local-outbound-connection:add(outbound-socket-binding-ref=outbound-socket-binding)
Deleting a Local Outbound Connection
/subsystem=remoting/local-outbound-connection=new-local-outbound-connection:remove
See Local Outbound Connection Attributes for a full list of the attributes available for configuring a local outbound connection.
17.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:
/subsystem=remoting/configuration=endpoint:write-attribute(name=worker, value=WORKER_NAME)
See Configuring a Worker for details on how to configure an IO worker.
- Network interface
The network interface used by the
remoting
subsystem is thepublic
interface. This interface is also used by several other subsystems, so exercise caution when modifying it.<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:127.0.0.1}"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address:127.0.0.1}"/> </interface> <interface name="unsecure"> <inet-address value="${jboss.bind.address.unsecure:127.0.0.1}"/> </interface> </interfaces>
In a managed domain, the
public
interface is defined per host in itshost.xml
file.- Socket binding
The default socket binding used by the
remoting
subsystem binds to port8080
.For more information about socket binding and socket binding groups, see Socket Bindings.
- Remoting connector reference for EJB
The
ejb3
subsystem contains a reference to the remoting connector for remote method invocations. The following is the default configuration:<remote connector-ref="remoting-connector" thread-pool-name="default"/>
- 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 EJBs, ORB, and the JMS provider, request secured interfaces by default.
WarningSTARTTLS 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.