Dieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.

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.

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

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

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

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

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

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

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

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

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

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

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

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:

/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 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="${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 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.

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 (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.

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.