Chapter 7 Transports and Endpoints

omniORB can support multiple network transports. All platforms (usually) have a TCP transport available. Unix platforms support a Unix domain socket transport. Platforms with the OpenSSL library available can support a TLS/SSL and HTTP(s) transport.

Servers must be configured in two ways with regard to transports: the transports and interfaces on which they listen, and the details that are published in IORs for clients to see. Usually the published details will be the same as the listening details, but there are times when it is useful to publish different information.

Details are selected with the endPoint family of parameters. The simplest is plain endPoint, which chooses a transport and interface details, and publishes the information in IORs. Endpoint parameters are in the form of URIs, with a scheme name of ‘giop:’, followed by the transport name. Different transports have different parameters following the transport.

TCP endpoints have the format:

giop:tcp:<host>:<port>

The host must be a valid host name or IP address for the server machine. It determines the network interface on which the server listens. The port selects the TCP port to listen on, which must be unoccupied. Either the host or port, or both can be left empty. If the host is empty, the ORB publishes the IP address of the first non-loopback network interface it can find (or the loopback if that is the only interface), but listens on all network interfaces. If the port is empty, the operating system chooses an ephemeral port.

Multiple TCP endpoints can be selected, either to specify multiple network interfaces on which to listen, or (less usefully) to select multiple TCP ports on which to listen.

If no endPoint parameters are set, the ORB assumes a single parameter of giop:tcp::, meaning IORs contain the address of the first non-loopback network interface, the ORB listens on all interfaces, and the OS chooses a port number.

TLS/SSL endpoints have the same format as TCP ones, except ‘tcp’ is replaced with ‘ssl’. Unix domain socket endpoints have the format:

giop:unix:<filename>

where the filename is the name of the socket within the filesystem. If the filename is left blank, the ORB chooses a name based on the process id and a timestamp.

To listen on an endpoint without publishing it in IORs, specify it with the endPointNoPublish configuration parameter. See below for more details about endpoint publishing.

7.1 Port ranges

Sometimes it is useful to restrict a server to listen on one of a range of ports, rather than pinning it to one particular port or allowing the OS to choose an ephemeral port. omniORB 4.2 introduced the ability to specify a range of ports using a hyphen. e.g. to listen on a port between 5000 and 5010 inclusive:

giop:tcp::5000-5010

omniORB randomly chooses a port in the range. If it finds that the chosen port is already occupied, it keeps trying different ports until it finds a free one. If all the ports in the range are occupied, it throws CORBA::INITIALIZE.

7.2 IPv6

On platforms where it is available, omniORB supports IPv6. On most Unix platforms, IPv6 sockets accept both IPv6 and IPv4 connections, so omniORB’s default giop:tcp:: endpoint accepts both IPv4 and IPv6 connections. On Windows versions before Windows Vista, each socket type only accepts incoming connections of the same type, so an IPv6 socket cannot be used with IPv4 clients. For this reason, the default giop:tcp:: endpoint only listens for IPv4 connections. Since endpoints with a specific host name or address only listen on a single network interface, they are inherently limited to just one protocol family.

To explicitly ask for just IPv4 or just IPv6, an endpoint with the wildcard address for the protocol family should be used. For IPv4, the wildcard address is ‘0.0.0.0’, and for IPv6 it is ‘::’. So, to listen for IPv4 connections on all IPv4 network interfaces, use an endpoint of:

giop:tcp:0.0.0.0:

All IPv6 addresses contain colons, so the address portion in URIs must be contained within [] characters. Therefore, to listen just for IPv6 connections on all IPv6 interfaces, use the somewhat cryptic:

giop:tcp:[::]:

To listen for both IPv4 and IPv6 connections on Windows versions prior to Vista, both endpoints must be explicitly provided.

7.2.1 Link local addresses

In IPv6, all network interfaces are assigned a link local address, starting with the digits fe80. The link local address is only valid on the same ‘link’ as the interface, meaning directly connected to the interface, or possibly on the same subnet, depending on how the network is switched. To connect to a server’s link local address, a client has to know which of its network interfaces is on the same link as the server. Since there is no way for omniORB to know which local interface a remote link local address may be connected to, and in extreme circumstances may even end up contacting the wrong server if it picks the wrong interface, link local addresses are not considered valid. Servers do not publish link local addresses in their IORs.

7.3 Endpoint publishing

For clients to be able to connect to a server, the server publishes endpoint information in its IORs (Interoperable Object References). Normally, omniORB publishes the first available address for each of the endpoints it is listening on.

The endpoint information to publish is determined by the endPointPublish configuration parameter. It contains a comma-separated list of publish rules. The rules are applied in turn to each of the configured endpoints; if a rule matches an endpoint, it causes one or more endpoints to be published.

The following core rules are supported:

The core rules can be combined using the vertical bar operator to try several rules in turn until one succeeds. e.g:

Multiple rules can be combined using the comma operator to publish more than one endpoint. e.g.

For endpoints with multiple addresses (e.g. TCP endpoints on multi-homed machines), the all() manipulator causes all addresses to be published. e.g.:

A specific endpoint can be published by giving its endpoint URI, even if the server is not listening on that endpoint. e.g.:

If the host or port number for a TCP or SSL URI are missed out, they are filled in with the details from each listening TCP/SSL endpoint. This can be used to publish a different name for a TCP/SSL endpoint that is using an ephemeral port, for example.

omniORB 4.0 supported two options related to endpoint publishing that are superseded by the endPointPublish parameter, and so are now deprecated. Setting endPointPublishAllIFs to 1 is equivalent to setting endPointPublish to ‘all(addr)’. The endPointNoListen parameter is equivalent to adding endpoint URIs to the endPointPublish parameter.

7.3.1 POA-specific endpoint publishing

It can sometimes to useful to publish different sets of endpoints for different objects in the same server. To enable that, you can create a POA with the omniORB-specific EndpointPublishPolicy, giving a sequence of endpoint strings:

The endpoints must be fully specified—unlike the global publish specifications, an empty port number is not filled with the chosen listening port.

Note that the publishing policy only affects the published endpoints—it does not change the global endpoints that the ORB is listening on to receive incoming connections.

7.4 Connection selection and acceptance

In the face of IORs containing details about multiple different endpoints, clients have to know how to choose the one to use to connect a server. Similarly, servers may wish to restrict which clients can connect to particular transports. This is achieved with transport rules.

7.5 Client transport rules

The clientTransportRule parameter is used to filter and prioritise the order in which transports specified in an IOR are tried. Each rule has the form:

<address mask> [action]+

The address mask can be one of

The action is one or more of the following:

The transport-selecting actions form a prioritised list, so an action of ‘unix,ssl,tcp’ means to use a Unix transport if there is one, failing that an SSL transport, failing that a TCP transport. In the absence of any explicit rules, the client uses the implicit rule of ‘* unix,ssl,tcp’.

If more than one rule is specified, they are prioritised in the order they are specified. For example, the configuration file might contain:

  clientTransportRule = 192.168.1.0/255.255.255.0  unix,tcp
  clientTransportRule = 172.16.0.0/255.240.0.0     unix,tcp
                      =       *                    none

This would be useful if there is a fast network (192.168.1.0) which should be used in preference to another network (172.16.0.0), and connections to other networks are not permitted at all.

In general, the result of filtering the endpoint specifications in an IOR with the client transport rule will be a prioritised list of transports and networks. (If the transport rules do not prioritise one endpoint over another, the order the endpoints are listed in the IOR is used.) When trying to contact an object, the ORB tries its possible endpoints in turn, until it finds one with which it can contact the object. Only after it has unsuccessfully tried all permissible endpoints will it raise a TRANSIENT exception to indicate that the connect failed.

7.6 Server transport rules

Server transport rules have the same format as client transport rules. Rather than being used to select which of a set of ways to contact a machine, they are used to determine whether or not to accept connections from particular clients. In this example, we only allow connections from our intranet:

  serverTransportRule = localhost                  unix,tcp,ssl
                      = 172.16.0.0/255.240.0.0     tcp,ssl
                      = *                          none

And in this one, we accept only SSL connections if the client is not on the intranet:

  serverTransportRule = localhost                  unix,tcp,ssl
                      = 172.16.0.0/255.240.0.0     tcp,ssl
                      = *                          ssl,bidir

In the absence of any explicit rules, the server uses the implicit rule of ‘* unix,ssl,tcp’, meaning any kind of connection (other than HTTP) is accepted from any client.

7.7 Bidirectional GIOP

omniORB supports bidirectional GIOP, which allows callbacks to be made using a connection opened by the original client, rather than the normal model where the server opens a new connection for the callback. This is important for negotiating firewalls, since they tend not to allow connections back on arbitrary ports.

There are several steps required for bidirectional GIOP to be enabled for a callback. Both the client and server must be configured correctly. On the client side, these conditions must be met:

• The offerBiDirectionalGIOP parameter must be set to true.
• The client transport rule for the target server must contain the bidir action.
• The POA containing the callback object (or objects) must have been created with a BidirectionalPolicy value of BOTH.

On the server side, these conditions must be met:

• The acceptBiDirectionalGIOP parameter must be set to true.
• The server transport rule for the requesting client must contain the bidir action.
• The POA hosting the object contacted by the client must have been created with a BidirectionalPolicy value of BOTH.

7.8 TLS / SSL transport

omniORB supports a TLS / SSL transport, using OpenSSL. It is only built if OpenSSL is available. On platforms using Autoconf, it is autodetected in many locations, or its location can be given with the --with-openssl= argument to configure. On other platforms, the OPEN_SSL_ROOT make variable must be set in the platform file.

To use the SSL transport, you must link your application with the omnisslTP library, and correctly set up certificates. See the src/examples/ssl_echo directory for an example. That directory contains a README file with more details.

7.8.1 Self-signed certificate authority

By default, omniORB configures OpenSSL to require both clients and servers to have certificates that are signed by a Certificate Authority (CA). It is possible to use a public CA to obtain keys that can be independently verified, but for many purposes, it is sufficient to use a private CA to sign all the keys in use in an application. The following is a brief description of how to become your own certificate authority and issue and sign certificates, using the OpenSSL command line tools.

Before starting, find the default openssl.cnf file that was installed with OpenSSL, copy it to a suitable location, and edit it as you feel appropriate. Now, build a certificate directory structure, authority key and certificate:

  mkdir demoCA demoCA/private demoCA/newcerts

  openssl req -config openssl.cnf -x509 -newkey rsa:2048 \
     -keyout demoCA/private/cakey.pem -out demoCA/cacert.pem -days 3650

  echo 01 >demoCA/serial
  touch demoCA/index.txt

Next, issue a key request and sign it:

  openssl req -config openssl.cnf -new -keyout server_key.pem \
     -out server_req.pem -days 3650

  openssl ca -config openssl.cnf -policy policy_anything \
     -out server_cert.pem -in server_req.pem 

Amongst other things, you now have a server key file in server_key.pem and a certificate in server_cert.pem. To make a single file containing both the key and the certificate, suitable for use in omniORB, concatenate the key and certificate files together. You can skip the human-readable(ish) text in the certificate file before the -----BEGIN CERTIFICATE----- marker.

If need be, create more certificates for servers and clients in the same way.

7.9 HTTP, HTTPS and WebSocket transport

omniORB includes an omniORB-specific HTTP transport. It works by encapsulating GIOP messages into HTTP messages, which can make it easier to transport through firewalls and proxies that understand HTTP but not GIOP. It supports the use of HTTP proxies, reverse proxies and load balancers. It can optionally establish WebSocket connections, which avoid many of the limitations of pure HTTP, but are not quite as widely accepted.

To use the HTTP transport, you must link with the omnihttpTP library.

7.9.1 HTTP limitations

Normal client-server CORBA calls match the semantics of HTTP — the client sends a request and blocks waiting for the server to respond, meaning that in simple uses, the communication is pure, valid HTTP, and can therefore safely pass through proxies. However, there are a number of situations in which GIOP semantics do not match HTTP. In these cases, the communication works if an omniORB client is connected directly to an omniORB server, but can fail if a proxy or other system is interpreting the HTTP messages along the communication path:

• If the oneCallPerConnection configuration parameter is set to the non-default value of false, a multi-threaded client can send multiple concurrent calls on a single connection, meaning multiple HTTP requests are made without waiting for each to receive a reply.
• If bidirectional GIOP is enabled, the server can send a message to the client that is not in response to a client request.
• Web proxies can choose to open new connections at any time, and therefore the client’s idea of the lifetime of a connection does not necessarily match what the server sees. This means that codeset information, which is only transmitted on the first call on a connection, may be missing from the point of view of the server.
• Some web proxies and load balancers routinely close connections after a client has sent a request, without sending the request on to the server. The client therefore sees the connection fail, but cannot know that the server did not receive the request. It therefore has to fail the call with a COMM_FAILURE exception with completion status COMPLETED_MAYBE. Application code must be prepared to handle the situation.

To minimise these issues with proxies, it is safest to keep oneCallPerConnection set to true, avoid bidirectional GIOP, and make use of the defaultCharCodeSet and defaultWCharCodeSet parameters to choose suitable codesets.

Alternatively, clients can ‘upgrade’ the HTTP connection to a WebSockets connection, in which cases messages are sent in a binary framing format that does permit the use of full GIOP semantics. Upgrading an HTTP connection to a WebSockets connection requires that all intermediary servers (proxies, load balancers, etc.) support the WebSocket protocol, so there are some environments in which plain HTTP communication succeeds but WebSockets fail.

7.9.2 Endpoint and transport rule specification

The HTTP transport uses endpoint URIs of the form giop:http:url, where the url is a full http://, https://, ws:// or wss:// URL. That means the URIs appear to duplicate the ‘http’:

giop:http:http://server.example.com:8000/call
giop:http:https://secure.example.com:443/invoke
giop:http:ws://websocket.example.com:8080/ws
giop:http:wss://websocket-secure.example.com:8443/ws

The path part of the URL can be set to any value. On the client side, the client makes an HTTP POST request to the URL, specifying the path; the server checks that the path matches what it expects. The ability to specify a path this way can be helpful when configuring path-based routing in load balancer configurations.

If no port is specified on the server endpoint, the server uses an ephemeral port; it does not default to 80 or 443.

Servers always support upgrade of connections to WebSocket. The use of a ws:// or wss:// URL determines the URL that is published in object references, and thus whether clients will attempt to use WebSockets or not.

The transport specification ‘http’ is not in the default client or server transport rules (as described in section 7.5). To enable the use of HTTP, the client and server transport rules could for example contain ‘* unix,tcp,ssl,http’.

7.9.3 Client connections

As with all other transports, a client can connect to a server that uses the HTTP transport using an IOR in string form, or an object reference received from another CORBA call. Clients can also connect by giving a suitable URL to ORB::string_to_object().

In this case, the URL should be a simple plain URL, not a corbaloc URI. The URL path must match the patch in the server’s endpoint specification. The CORBA object key should follow a # character:

For this to work, the server should publish objects with plain object keys, as described in section 8.5.

7.9.4 HTTP proxies

Clients can connect via a web proxy. The httpProxy configuration can be set to an http or https proxy URL. If the proxy requires basic authentication, the httpProxyUsername and httpProxyPassword parameters can be set.

When connecting through a proxy, the behaviour depends on whether the client is connecting to an HTTP or HTTPS server, and whether it is attempting to use WebSockets. When connecting with plain HTTP, the request is sent directly to the proxy, and the proxy forwards it at an HTTP level. In this situation, it is essential that only pure HTTP-compliant messages are sent.

When connecting to an HTTPS server or upgrading the connection to WebSockets, the client makes a CONNECT request to the proxy. If accepted by the proxy, that opens a transparent tunnel through to the server. In that situation, as long as nothing else intercepts and attempts to interpret the data, the omniORB client is in effect directly connected to the omniORB server, and there is more chance that transfers that are not strictly legal HTTP will succeed.

7.9.5 HTTPS keys and certificates

Support for HTTPS uses the same concepts as the SSL transport. For each configuration option with a name starting ‘ssl’, there is an equivalent option starting ‘https’.

7.9.6 In-message encryption

In some environments, the use of HTTPS is not sufficient to guarantee end-to-end security between client and server. There are at least two situations in which that can arise:

• Some transparent web proxies intercept HTTPS connections and act as a decrypting man-in-the-middle. For that to work, the client and server must accept the proxy’s certificates of course, but that may be the only way for the client to connect to the server.
• On the server side, it can be useful to have a load balancer that performs HTTPS off-load in front of the server. In that case, the client connects with HTTPS, but the server sees a plain HTTP connection.

To ensure message security in those cases, the HTTP transport supports in-message encryption, with pluggable encryption implementations. See include/omniORB4/httpCrypto.h for the interfaces. The omnihttpCrypto library provides an implementation that uses AES-256 for message encryption and RSA with pre-shared public keys for key transfer. To use it, on the server side, registering the public keys of two known clients:

and on the client:

7.10 ZIOP

omniORB has support for ZIOP, which compresses transmitted messages. To use it, link with the omniZIOP4 library.

On Unix platforms, ZIOP support is automatically enabled if the configure script detects zlib. To enable it on Windows, set the EnableZIOP make variable in the platform configuration file.

omniORB has an almost complete implementation of the ZIOP specification, with the following extensions and differences:

1. To avoid a dependency on CORBA::Any, compression policies can be obtained with functions in the omniZIOP namespace, rather than with the standard orb->create_policy(). See include/omniORB4/omniZIOP.h for details. To use Any with the standard orb->create_policy(), link with the omniZIOPDynamic4 library in addition to omniZIOP4.
2. Client-side policies are global, set with omniZIOP::setGlobalPolicies(). CORBA::Object::_set_policy_overrides() is not supported.
3. POAs can be given ZIOP policies as shown in the src/examples/ziop/ziop_impl.cc, but they can also use the global policies set with omniZIOP::setGlobalPolicies(). This is useful to apply ZIOP policies to the RootPOA or omniINSPOA.

In addition to the standard policies, whether or not to enable ZIOP is determined by client and server transport rules. For a client to use ZIOP, the matching client transport rule must include ‘ziop’; similarly, for a server to use ZIOP, the matching server transport rule must include ‘ziop’. e.g. to use the examples:

  ziop_impl -ORBserverTransportRule "* unix,ssl,tcp,ziop"

  ziop_clt -ORBclientTransportRule "* unix,ssl,tcp,ziop" IOR:...

This allows you to enable ZIOP for WAN links, but disable it for LAN communication, for example.

7.10.1 Forcing ZIOP Policies

The fact that a server supports ZIOP is encoded in its IORs. This means that if a client uses a corbaloc URI to reference an object, the object reference does not contain ZIOP details, and thus the communication cannot use ZIOP. If a client is absolutely certain that a server supports ZIOP, it can extend an object reference with ZIOP details using omniZIOP::setServerPolicies(). Using the new object reference, the client will be able to make ZIOP calls.

Creating a ZIOP-enabling object reference in this way is dangerous! If the server does not actually support ZIOP, it will receive compressed messages that it cannot handle. A well-behaved server will throw a CORBA::MARSHAL exception in response, or perhaps just drop the invalid connection.

7.11 Connection Management Extension

The omniConnectionMgmt library provides an omniORB-specific extension for application-level connection management. Its purpose is to allow clients and servers to negotiate private GIOP connections, and to control how the connections are used in multi-threaded situations.

The omniConnectionMgmt library has two functions, defined in include/omniORB4/omniConnectionMgmt.h:

The init() function must be called before CORBA::ORB_init() in every process that is to take part in the connection management.

The makeRestrictedReference() function is the single entry-point to the connection management functionality. It builds an annotated object reference that contains information for the connection management system. It returns a new reference, leaving the original object reference unchanged.

7.11.1 Client-side parameters

These parameters affect the client side of a connection:

connection_id

This number identifies the private connection set. All object references with the same connection_id will share the same set of GIOP connections. Object references with different connection ids are guaranteed to use different connections from each other, and from object references that have not been annotated with makeRestrictedReference().

max_connections

This parameter overrides the omniORB maxGIOPConnectionPerServer configuration parameter for the given connection_id. It determines the maximum number of separate GIOP connections that will be opened to the object’s server to service concurrent calls. It is common to set this value to 1, indicating that only one connection will be used for the given connection_id. Note that this parameter can only be used to reduce the default maxGIOPConnectionPerServer value, not increase it.

data_batch

omniORB usually configures its TCP connections to disable Nagle’s algorithm, which batches small messages together into single IP packages, since that is best for the usual CORBA usage pattern of two-way requests. Setting this parameter to true overrides that, and enables Nagle’s algorithm on TCP connections or equivalent functionality on other transports. This can increase throughput if a client is sending a large number of small oneway calls.

permit_interleaved

This parameter overrides the oneCallPerConnection configuration parameter that determines whether multi-threaded clients can interleave calls on a single connection, issuing a new request message while a previous request is still waiting for a reply. If permit_interleaved is true, clients can interleave messages; if it is false, they cannot.

7.11.2 Server-side parameters

These parameters affect the client side of a connection:

max_threads

This parameter overrides the global maxServerThreadPerConnection configuration parameter that determines the maximum number of concurrent threads the server will use to service requests coming from a connection. Note that this parameter is only relevant if either the client permits interleaved calls, or if oneway operations are used, since those are the only circumstances under which the server can receive a new request on a connection while already handling a request. As with the max_connections client-side parameter, this parameter can only reduce the default number of threads, not increase it.

server_hold_open

Normally, both clients and servers can decide to close a GIOP connection at any time. When using normal two-way calls, this is no problem since if a server closes a connection, the client is guaranteed to notice it when it waits for a reply, and can retry the call if necessary. With oneway calls, however, if a server closes a connection just as the client is sending a request, the client will not know whether the oneway call was received or not, and the call will potentially be lost. By setting the server_hold_open parameter to true, the server will not close the connection, relying on the client to do so. In that case, oneway calls will not be lost unless there is a network problem that breaks the GIOP connection.

7.11.3 Usage

The omniConnectionMgmt extension is very easy to use—simply call the init() method in all processes involved, then restrict references as required. The makeRestrictedReference() function adds profile information to the object reference’s IOR, meaning that the parameters become part of the object reference and are transmitted along with it. In other words, a server can create a restricted reference and send it to a client, and the client will automatically make use of the restricted parameters when it invokes operations on the object reference. Alternatively, a client can restrict a normal reference it receives, in order to change its own behaviour.